Tips, Tricks, and Best Practices

Hi, my name is Siarhei, and I’m a Software Engineer with over 10 years of experience in iOS app development. During my career, I have worked with many teams to create multilingual apps for different audiences and industries. This experience has taught me a lot about the tools and services used for localization and the common challenges developers face. Over the years, localization has become much easier and cheaper, making it more accessible than ever.

However, even when using professional translators or AI tools, developers play an important role in the localization process. We need to provide clear and well-structured text for translation and ensure that all content is displayed correctly in the app. I’ve seen skilled developers make mistakes because they didn’t know the differences between languages. These mistakes often go unnoticed because everything looks correct in their own language.

In this article, I’ll share simple tips and best practices to help developers create apps that feel natural for users, no matter their language. This guide will be helpful for both new and experienced developers, not just for iOS but for all Apple platforms. Let’s explore how we can make localization better and easier for everyone.

String vs. LocalizedStringKey

One of the first things to understand is how strings are handled. Let’s start with two examples:

let string = "Hello World!"
Text(string)

Text("Hello World!")

At first glance, these examples might seem identical, but they behave differently because of the types of data passed to Text. In the first example, the constant string is implicitly inferred to be of type String because it’s initialized with a string literal. When passed to Text, the String object is used directly, and the text “Hello World!” is displayed as plain text.

In the second example, the string literal “Hello World!” is directly passed to Text. Here, the literal is treated as an instance of LocalizedStringKey, because Text by default expects an object of type LocalizedStringKey. In this case, “Hello World!” is not treated as a value but as a key. The result is determined as follows:

• If the key “Hello World!” exists in the default localization table, the corresponding value will be displayed.
• If no entry is found for the key, Xcode may automatically add this string to the default String Catalog file (if this option is enabled in Build Settings). In this case, the key itself will be displayed.

If you do not want to use the default localization table, you can specify a custom table with the tableName parameter. You can also define the source of localization files by using the bundle parameter.

Text("Hello World!", tableName: "CustomLocalizations", bundle: .main)

If you want to make sure that your string is not added to the String Catalog file and is displayed as-is, you can use

Text(verbatim: "Hello World!")

or explicitly pass a String object.

The same logic with LocalizedStringKey applies to other UI elements in SwiftUI. Always be careful about the type of object that a view expects to display.

If your strings are initialized outside of views, such as in business logic, or if you work with UIKit or AppKit, you can still use translations and automatically add strings to String Catalog files. To do this, use the following approach:

let string = String(localized: "Hello World!")

If you want to use a non-default localization file, you can specify it like this:

let string = String(
    localized: "Hello World!", 
    table: "CustomLocalizations", 
    bundle: .main)

Understanding this behavior is critical for ensuring that strings are localized correctly. It also highlights the importance of carefully managing your localization files to avoid unexpected results.

Providing Context

Providing translators with context is essential for ensuring accurate translations. Whether your app is translated by a human or AI, a lack of context can lead to incorrect results. This is especially important for short strings, where it might be impossible to determine the part of speech or the intended meaning without additional information. To avoid such issues, you can add an optional comment to explain the string’s purpose:

Text("Hello World!", comment: "Comment for translator")

let string = String(
    localized: "Hello World!",
    comment: "Comment for translator")

The comment you provide will automatically be included with the string in the String Catalog file.

Using a string as both the key and value for the main language is convenient, but it can sometimes lead to problems in other languages. For example, imagine a screen with a title “Archive” and a button labeled “Archive” that moves items into the archive. In code, this might look like:

Text("Archive")

Button("Archive")

Both the button and the title would reference the same string in the localization table. While this might work in some languages, in many others, the noun and verb forms of “Archive” would require different translations.

If you notice that identical strings have different meanings depending on their context, it’s better to create separate keys for them. This can be done as follows:

let archiveTitle = String(
    localized: "archive.label",
    defaultValue: "Archive",
    comment: "Name of the Archive folder in the sidebar")
// EN: Archive
// ES: Archivado
// RU: Архив

let archiveAction = String(
    localized: "archive.menuItem",
    defaultValue: "Archive",
    comment: "Menu item title for moving the email into the Archive folder")
// EN: Archive
// ES: Archivar
// RU: Архивировать

By creating unique keys for strings with different contexts, you ensure that translations are accurate and meaningful for all languages.

Pluralization

Localizing strings with numerical variables is a common task, but it can also be a source of issues if not done correctly. Often, you might see code like this:

Text(count == 1 ? "\(count) apple" : "\(count) apples")

While this may work for English, it poses significant challenges for other languages. Words that depend on numbers often change based on complex grammatical rules. For example, in Russian:

• 1 яблоко
• 2 яблока
• 5 яблок
• 20 яблок
• 21 яблоко

These variations follow specific pluralization rules, which can differ greatly across languages. The complete set of these rules is available on the CLDR Unicode website.

To handle pluralization correctly, you can start by writing:

Text("\(count) apples")

Then, in your String Catalog file, right-click on the string and select “Vary by Plural” from the context menu. After enabling pluralization, update the fields for your main language. For example, in English:

• In the “One” field, enter %lld apple.
• In the “Other” field, enter %lld apples.

For each supported language, additional fields will appear, allowing you to provide translations that follow the CLDR rules.

Another way to handle pluralized strings is by using automatic inflection:

Text("^[\(count) apple](inflect: true)")

The word will automatically change based on the value of “count”. This works for both countable and uncountable nouns:

let count = 3
Text("^[\(count) person](inflect: true)")   // 3 people
Text("^[\(count) company](inflect: true)")  // 3 companies
Text("^[\(count) deer](inflect: true)")     // 3 deer

While this method works well, it has a significant limitation: it does not support all languages. You can check if a language is supported using the following code:

let canInflect = InflectionRule.canInflect(language: "<language_code>")
// or
let canInflect = InflectionRule.canInflectPreferredLocalization

Currently supported languages are:

• iOS 16: English, Italian, Spanish, Portuguese, French
• iOS 17: English, Italian, Spanish, Portuguese, French, German
• iOS 18: English, Italian, Spanish, Portuguese, French, German, Korean, Hindi

On iOS 15, the canInflect function returns true for English, Italian, Spanish, Russian, and Swedish, but in reality, only English and Spanish are supported.

Due to the limited support for this feature, I would still recommend using the manual approach with String Catalog to ensure broader language compatibility.

Formatting Data

It’s common to see code like this:

Text("\(price)$")

While this might work in specific cases, it fails to account for how data is displayed in different regions. Even countries that share the same language can use different formats for various types of data. Thankfully, Apple has already implemented logic to handle these variations.

The formatted function is a powerful tool that adapts values based on the current locale. It supports translations for unit names, including plural forms, and can be used for a wide range of data. For example, prices, percentages, and dates can be formatted automatically as follows:

let currency = 1390.5.formatted(.currency(code: "USD"))
// en_US: $1,390.50
// es_ES: 1390,50 US$
// ru_RU: 1 390,50 $

let percent = 25.formatted(.percent)
// en_US: 25%
// es_ES: 25 %
// tr_TR: %25

let date = Date().formatted(.dateTime)
// en_US: 1/25/2025, 8:10 PM
// es_ES: 25/1/2025, 20:10
// ru_RU: 25.01.2025, 20:10

Another example is the formatting of lists, which can vary depending on the language. Apple’s tools make it easy to handle these differences:

let list = ["iPhone", "iPad", "Apple Watch"].formatted(.list(type: .and))
// en_US: iPhone, iPad, or Apple Watch
// es_ES: iPhone, iPad y Apple Watch
// ru_RU: iPhone, iPad и Apple Watch

Apple also provides a way to display most physical units of measurement in the correct format for any region using the Measurement structure. For example, to display temperature:

let measurement = Measurement(
    value: 24,
    unit: UnitTemperature.celsius)
let temperature = measurement.formatted(.measurement())
// en_US: 75.2°F
// es_ES: 24°C
// ru_RU: 24 °C

The unit parameter supports various types of measurements. Here’s the full list:

• UnitAcceleration: Unit of measure for acceleration.
• UnitAngle: Unit of measure for planar angle and rotation.
• UnitArea: Unit of measure for area.
• UnitConcentrationMass: Unit of measure for concentration of mass.
• UnitDispersion: Unit of measure for dispersion.
• UnitDuration: Unit of measure for duration of time.
• UnitElectricCharge: Unit of measure for electric charge.
• UnitElectricCurrent: Unit of measure for electric current.
• UnitElectricPotentialDifference: Unit of measure for electric potential difference.
• UnitElectricResistance: Unit of measure for electric resistance.
• UnitEnergy: Unit of measure for energy.
• UnitFrequency: Unit of measure for frequency.
• UnitFuelEfficiency: Unit of measure for fuel efficiency.
• UnitIlluminance: Unit of measure for illuminance.
• UnitInformationStorage: Unit of measure for quantities of information.
• UnitLength: Unit of measure for length.
• UnitMass: Unit of measure for mass.
• UnitPower: Unit of measure for power.
• UnitPressure: Unit of measure for pressure.
• UnitSpeed: Unit of measure for speed.
• UnitTemperature: Unit of measure for temperature.
• UnitVolume: Unit of measure for volume.

The formatted function is versatile and can be applied to various types of data, such as numbers, dates, times, intervals, and even people’s names. I recommend exploring its parameters and capabilities. It not only simplifies localization but also saves time by automating data formatting and conversion logic.

Localizing User Interface

Localization goes beyond adapting text — it’s about ensuring that your app feels natural and intuitive for users in different regions. People may interact with your app differently depending on their language and cultural norms.

For example, in languages like Arabic or Hebrew, the interface is read from right to left (RTL). Fortunately, standard interface components in Apple’s frameworks already support RTL layouts. To ensure your app handles this seamlessly, use leading and trailing constants instead of left and right when designing your interface. Only use left and right constants for components that should remain in fixed positions regardless of the language.

Another important factor to consider is font compatibility. While custom fonts can be used, I recommend the standard San Francisco font family because it is highly optimized for various languages, provides excellent readability, and ensures proper support for a wide range of characters and symbols. Custom fonts, on the other hand, may not support certain symbols or scripts required for some languages. If your design requires a custom font, ensure that all texts are thoroughly tested across all supported languages to avoid display issues.

Images can also be localized through the asset catalog. While it’s best to avoid placing text directly on images, there are cases where you may need to show different images or icons for specific regions. Apple makes this easy with localized asset variants.

For icons, I highly recommend using SF Symbols. These symbols automatically adapt to different languages and provide consistent visuals across your app.

By considering these aspects of localization, you can create an app that not only displays the right text but also feels tailored to users from any part of the world.

Styling Text Without Breaking Localization

When styling text, it’s essential to keep the entire string intact. A common mistake is splitting a sentence into multiple AttributedString segments and then concatenating them:

var hello = AttributedString(localized: "Hello")
hello.font = .system(size: 12)
hello.foregroundColor = .black

var world = AttributedString(localized: " World")
world.font = .system(size: 17)
world.foregroundColor = .white

let result = hello + world

At first glance, this approach may seem reasonable, but in reality, it creates two separate strings in the String Catalog. This can lead to translation issues because word forms depend on each other in many languages. The number and order of words may also change depending on the language. Additionally, in some cases, you may need to style individual letters rather than entire words, making proper localization even more challenging.

Instead of splitting strings, you can use built-in Markdown formatting or external libraries like swift-markdown-ui or BonMot. These tools allow you to apply different styles to parts of a string while keeping it as a single translatable unit.

If you prefer not to add an extra dependency or need more fine-grained control over text formatting, you can use custom attributes in AttributedString. While this requires additional code, it allows you to apply styles dynamically without breaking localization.

For example, a localized string might look like this:

How to implement custom attributes is beyond the scope of this article, but you can check out Apple’s example, which also demonstrates formatting options for other types of data.

Conclusion

I currently live in a country where I don’t speak the national language. Seeing even partial localization in local apps and websites makes a big difference for me. Even machine translation helps a lot because it allows me to guess what will happen when I click a button and feel more confident that I won’t accidentally do something wrong.

I highly recommend translating your apps into as many languages as possible. It can be a competitive advantage, helping you reach more users and stand out in the market. I understand that hiring professional translators can be expensive, but for secondary languages, using AI is a cost-effective solution. For just a few dollars, you can add support for a new language.

The key is to provide enough context for translations, which greatly improves its quality. You can do this manually or use existing services designed for localization. I’ve tried many of these services and eventually built my own macOS app that translates strings using context from comments. If you find it helpful, I’d be very glad. You can check it out here.

I’d also love to hear your thoughts in the comments. It would be great if you shared insights about the unique aspects of your native language and any additional localization tips you might have.

Thank you for reading to the end!

For solo developers, small teams, and startups, localizing an app can be a tough and expensive challenge. Hiring professional translators often comes at a high cost, making it difficult for many to bring their products to a global market. However, reaching a worldwide audience is crucial because it allows you to test your app in different regions and expand your user base. Machine translation might seem like a quick and cheap solution, but the quality often isn’t good enough. Traditional machine translators usually miss the full context, leading to awkward and confusing translations that can frustrate users. However, with the rise of advanced AI models like GPT, this is starting to change. Now, we can use AI to translate apps by providing the context needed to create more accurate and meaningful translations. While the results aren’t perfect yet, they’re good enough to allow users to comfortably interact with the app in their native language.

For my projects, I initially used ChatGPT to help with localization. I would manually copy strings from my Xcode project into the chat, explaining the context. After receiving the translations, I’d paste the results back into the strings catalog in Xcode. This process was incredibly monotonous and time-consuming. I assumed someone must have already automated this process, so I started searching for existing solutions. I found quite a few tools, both free and paid, that attempted to address this problem, but none of them fully met my needs. Most tools simply translated the strings without considering the context, which defeats the purpose of using modern AI. As a result, the translations were often inaccurate or awkward. Other tools had limitations in supporting different types of strings. For instance, they struggled with complex plural strings. But the biggest issue for me was that my projects included strings with Markdown or HTML formatting. These are essential when you need to emphasize certain words within a sentence that cannot be split into different strings. During translation, the formatting was often lost, which was unacceptable. After searching and not finding a solution that truly met my needs, I decided to create my own translation tool.

When I started building the tool, I quickly faced the difficulties of working with AI, especially with something called AI “hallucinations”. I learned firsthand that, even with straightforward requests, AI can sometimes produce completely unacceptable responses. This experience led me to explore prompt engineering more deeply and try different techniques to make the results more reliable. Here are some key insights I gathered along the way:

1. AI models like those from OpenAI can’t read your mind. They’re designed to always provide some kind of response, even if it’s not exactly what you intended. The models aim to please, but they can only work with what you give them. Therefore, it’s crucial to craft your prompts as precisely as possible to guide the AI toward the desired outcome.
2. While it’s essential to be precise, I’ve found that overly detailed and lengthy prompts can sometimes overwhelm the AI, causing it to miss or ignore certain requirements. It’s often more effective to break down a large task into smaller, more focused subtasks. This way, the AI can concentrate on one specific aspect at a time, leading to more accurate and consistent results.
3. I also noticed that AI understands instructions much better when provided with examples. By structuring your prompt with clear examples of the desired format or outcome, you can significantly improve the quality of the responses. Think of it as having a conversation with the AI — show it what you mean, rather than just telling it.
4. Fine-tuning the model can be a powerful way to shorten prompts and teach AI concepts that are hard to convey purely through text. However, it’s essential to be very careful with the data you use for training. During fine-tuning, the model will prioritize this new information over its base knowledge, which can lead to worse performance on tasks that weren’t covered by the training data.
5. Interestingly, I discovered that older models like GPT-3.5 tend to be more straightforward and are excellent at executing short, clear tasks. On the other hand, the newer models, like GPT-4o and GPT-4o mini, might add extra information even if you didn’t ask for it, but they handle more complex and longer prompts better. They also tend to ignore fewer requirements, making them more reliable for intricate tasks.
6. After receiving a response from the AI, you can ask it to review its own output to ensure that all requirements have been met. This step can help catch any missed details or errors that may have slipped through.
7. Another technique is to send the same prompt multiple times, either to the same model or different models, and then ask the AI to vote on the best response. This approach helps filter out AI hallucinations or results that do not meet all conditions.
8. Finally, even when you think you’ve crafted the perfect prompt, it’s essential to test it across a large number of examples. Sometimes, what works well on a few test cases may perform poorly on a broader set of data. Thorough testing is key to ensuring consistent results.

Through a combination of these approaches, I was able to significantly reduce AI hallucinations and improve the accuracy of the results. To translate a single string into one language, I need to provide a fairly lengthy prompt with examples and perform multiple requests to refine the output and filter out incorrect results. While this process makes each translation more costly than I initially expected, it is still incomparably cheaper than using human translators.

I also spent far more time developing this tool than I originally anticipated. However, the result is a highly useful utility that effectively meets my needs. While it may not be a perfect translation tool, it is good enough to launch apps in different markets. Given its usefulness, I decided to package it into a convenient macOS application and make it available on the App Store.

The application is designed specifically for translating Xcode projects that use the modern String Catalog files to manage strings. It supports all types of strings, including complex plural strings and device-specific variations. My goal was to automate as much of the process as possible while still allowing full control when needed. One of the key features is that there’s no need to export or import strings manually. Simply open your Xcode project in the app, and all strings and their statuses will be automatically synchronized.

From there, you can click the “Run” button to automatically translate all untranslated strings into the languages supported by your project. You can choose which AI model to use for translations. As I mentioned earlier, for complex tasks, it’s sometimes better to use more advanced (and expensive) models, but in most cases, the less expensive ones work just fine. I’ve added an automatic mode that dynamically selects the model based on the type of string and its context. However, you can also experiment and manually select the model that works best for your needs. In the future, I plan to add more models, not just from OpenAI.

You can also choose which strings to translate based on their status and select the languages to which they should be translated.

If you prefer to have more control over the translation of each string, you can translate them one by one for all languages or for a specific language using the context menu.

Additionally, if needed, you can manually translate or edit the text to ensure it meets your exact requirements.

Regardless of who or what is localizing your app, it’s a best practice to include comments with your strings to give more context to the translators. My application will pass these comments along to the AI to help better explain the context. While comments are not mandatory, they can greatly enhance the accuracy of the results. For example, in English, a word can sometimes function as both a noun and a verb, while in other languages, these forms might look very different. In such cases, providing additional context through comments is crucial to ensure the translation is accurate. Without this extra information, the AI or a human translator might misinterpret the intended meaning, leading to errors in the localized version.

let archiveFolderName = String(
    localized: "Archive.label",
    defaultValue: "Archive",
    comment: "Name of the Archive folder in the sidebar")

// EN: Archive
// ES: Archivado
// RU: Архив

let archiveMenuItemTitle = String(
    localized: "Archive.menuItem",
    defaultValue: "Archive",
    comment: "Menu item title for moving the email into the Archive folder")

// EN: Archive
// ES: Archivar
// RU: Архивировать

By including clear and concise comments, you can help the AI understand the specific use of each string, whether it’s a button label, a menu item, or an error message. This simple step can make a big difference in the overall quality of the localized app.

Thank you for taking the time to read through this article. If you find my app useful, I invite you to download it from the App Store and give it a try. I have plenty of ideas on how to improve the tool, but I’m always open to feedback. If you have any comments or suggestions, feel free to reach out to me via email. Your insights could help make this app even better for everyone.