Easy Way to Build iOS Apps that Support Multiple User Languages on UIkit and SwiftUI Using String Catalog
An application definitely wants to be used by a lot of people and be accessible to users in multiple countries and regions. One strategy that may provide all of this is to develop an application that supports multiple languages. This is important since users will find it comfortable and easy to use the application.
Localization is the process of translating and adapting your app into multiple languages and regions. ~ Apple Localization Documentation
We can build iOS applications that support multi-languages, often known as localization. The following instances include:
- Strings: This approach can be applied to string or text localization. It contains keys and values for retrieving localized text. However, the disadvantage of this technology is that it does not allow plural and does not have a graphic user interface (GUI), making errors quite possible. The most common issue is having text that has not been altered in multi-languages.
- Stringsdict: This approach can be applied to plural text localization. Stringdict, like String, is not supported by a proper GUI, making it more likely to errors.
- String Catalog: Apple recommends this approach for iOS localization. It introduced at WWDC 2023, however it requires Xcode 15 or higher.
In this tutorial, we will use String Catalog and discuss it in more details. So, prepare some coffee first, then take a deep breath, to boost your motivation for learning 😁
String Catalog
String Catalog replaces String and Stringdict with a new format that includes a GUI and workflow. String Catalog makes it easier to localize text and plurals.
The advantages of String Catalog include:
- It is equipped with a proper GUI. We can change the translation using the GUI or visual provided and view the percentage of text that has been translated. In that GUI, we can also add comments that might explain the context of the translated text.
- Workflow is more clearly defined. The GUI provided by XCode allows us to see and change the status of the text translation. The available statuses are New, Need Review, Reviewed, and Stale. So we will know if new text has been added or changed, or if existing text has to be reviewed again.
- Used to translate both text and plural. In plural, we can translate based on number (zero, one, and other) or platform (iOS, macOS, watchOS).
- Can easily export and import localization text assets. This feature is especially helpful when there is lot of text to be translated and needs translation services. We simply send the exported localization file to the translator, the translator directly translates in that file, and then we import the translated file into our iOS project. As a result, the translated text will be automatically filled in. Easy, isn’t it? 😄 We, as iOS developers, no longer have to fill in text one by one.
Implement String Catalog in UIKit
- Create a new project with the storyboard interface.
2. Add 3 labels to the storyboard as examples of translation results. Arrange all constraints so that the display looks like the image below.
3. Add a String Catalog file to the project by clicking File -> New File -> Select String Catalog -> Next -> Create. If this process is successful, .xcstrings format file with the default English localization will be created.
4. In the GUI String Catalog, add localization text for English.
The next question is, what exactly do %@, %lld and %.1f mean?
%@, %lld and %.1f are called out to be String Format Specifiers. It is easy to see that %@, %lld and %.1f will be replaced by strings with specific formatting.
%@: String
%lld: Integer
%.1f: Float with 1 digit following the decimal point.
For more details, you can visit this link.
5. Add a plural condition in the string catalog. To do this, right-click on the key -> select Vary by Plural -> select Argument 1. Repeat this steps to select argument 2.
Next, add the plural, as shown in the image below.
Since English supports plurals, one and the other will appear. One refers to the singular, while the other refers to the plural.
6. To add another localization target, click the + button at the bottom -> select a country.
7. Add a translation and plural condition for Indonesian. The approach is same to step 5. Because Indonesian does not accept plurals, the only option displayed is other.
8. In ViewController, add IBOutlet for 3 labels, connect them to the storyboard, and assign localization text to those labels.
import UIKit
class ViewController: UIViewController {
@IBOutlet weak var message1Label: UILabel!
@IBOutlet weak var message2Label: UILabel!
@IBOutlet weak var message3Label: UILabel!
let name = "Galang"
let applicationCount = 6
let yearExperience = 3.5
override func viewDidLoad() {
super.viewDidLoad()
message1Label.text = String(localized: "Hello, world! My name is \(name)")
message2Label.text = String(localized: "I love coding")
message3Label.text = String(localized: "After \(yearExperience, specifier: "%.1f") year(s) experience, i have released \(applicationCount) application(s)")
}
}9. To check whether localization works or not, we can run a simulation by changing the schema language settings.
10. Done, now try running the application.
Implement String Catalog in SwiftUI
SwiftUI will make implementation easier than UIKit.
- Create a new project with the SwiftUI interface.
2. In ContentView, add 3 texts in the body as examples of translation results.
import SwiftUI
struct ContentView: View {
let name = "Galang"
let applicationCount = 6
let yearExperience: Double = 3.5
var body: some View {
VStack(alignment: .leading, spacing: 20) {
Text("Hello, world! My name is \(name)")
Text("I love coding")
Text("After \(yearExperience, specifier: "%.1f") year(s) experience, i have released \(applicationCount) application(s)")
}
.padding()
}
}
#Preview {
ContentView()
}3. Add a String Catalog file to the project by clicking File -> New File -> Select String Catalog -> New (the same as step 3 in UIKit).
4. Build the project, and the English translation will be automatically filled in. The Magic of SwiftUI 😁
5. Add a plural condition for English (the same as step 5 in UIKit).
6. To add another localization target, click the + button at the bottom -> select a country (the same as step 6 in UIKit).
7. Add a translation and plural condition for Indonesian (the same as step 7 in UIKit).
8. To check whether localization works or not, we can run a simulation by changing the schema language settings (the same as step 9 in UIKit).
9. Done, and you can see the results in the preview.
Bonus Part : Migrating from Legacy String to String Catalog
To migrate from a project that previously used String to String Catalog, we do not need to raise the iOS target higher. XCode already provides simple migration to String Catalog. We also do not have to move the text manually. Steps are as follows:
- Right-click on the localization String -> Select migrate to String Catalog -> Select Migrate.
2. When the migration is complete, our String file will be replaced by XCStrings, indicating that the migration was successful.
Thanks to the Apple team for making the migration process easier😊
Congratulations, you’ve completed the String Catalog tutorial. It’s quite easy, isn’t it? Do we have to use String Catalog for localization in our iOS project? In my opinion, if we create a new project, we should use String Catalog directly, as Apple recommends. In the future, we don’t know whether Apple will require the use of String Catalog or not.
Should projects that previously used String be migrated to String Catalog? I don’t think so, because we must also consider necessities. But, given all of the advantages, I recommend utilizing String Catalog.
Thank you for reading all the way through this tutorial.
Don’t forget to clap and follow if you find this article useful hehe :) See you in the next article!
Resources:
