Translate your app using agents in Xcode

Hello! I'm Avery, an engineer on the Localization team.

Today I'd like to talk to you about translating your app using agents in Xcode.

When you localize your app into other languages, you expand your app's audience to millions more people around the world. This is why at Apple, we're always striving to make it as easy as possible to localize your app.

In the past, traditional machine learning models have had a tough time with many aspects of software localization. Modern LLMs have solved several of these problems and are great at general-purpose translation, but they can still struggle with software localization when they don't have the right context. For example, consider the word 'book'. Is this referring to something to read? Or perhaps an action I would take to reserve a room at a hotel.

These words look the same in English, but have completely separate translations in other languages! Without further context, the wrong translation could be chosen, which would be misleading. The good news is, Xcode has been gaining context about your strings since the introduction of String Catalogs! Two years ago, String Catalogs started tracking where in code your strings are used. Last year, they started tracking how your strings are used, so they could automatically generate descriptive comments. And this year, we're excited to bring all of that context together! Beginning in Xcode 27, you can now translate your strings directly in Xcode using coding agents! I'll show you how you can add translations to your app, some techniques for reviewing and iterating on your translations, and finally, best practices you can follow to get the most out of these features. Let's get started! I've been developing an app that helps me learn about different landmarks from around the world and I'd like to make my app available to people around the world too! Since I grew up in Canada, let's start with Canadian French. I'm using SwiftUI, which means my app's UI is already localizable. For example, I'm using APIs like Text and Button, which automatically expose their strings for localization. I'm in a good place to start translation, so I'll ask an agent to translate my app into Canadian French, using the New Conversation button in Xcode's toolbar.

And with that, the agent and Xcode begin working together to translate my strings, step by step. The agent starts by telling Xcode to prepare the project for localization.

Xcode begins by adding the language to the project settings in our case, Canadian French. Then, Xcode builds all of your targets for your supported platforms. This is important to ensure that all of the localizable strings in your project are properly discovered. Finally, any newly discovered strings are added to String Catalogs. If there aren't any String Catalogs in your project yet, Xcode creates them automatically. By default, strings are added to a String Catalog called Localizable. Of course, you can also use custom table names, to help you organize your strings. For example, using the table name Greetings automatically puts your strings in a String Catalog called Greetings. Looks like Xcode is done preparing the project. Looking at the navigator on the left, I can see four brand new String Catalogs. Great! Next, the agent selects the strings that need translating. In my case, I've asked it to do the whole project, so it reads all four String Catalogs. Finally, the real work can begin! The agent splits the strings into batches, delegating the translation work to individual subagents.

Xcode gives subagents context about each string being translated. This can include information like where in code the string is used, or a list of strings that use similar terminology. It can even reference how the string was translated in other languages! Let's take a look at the String Catalog on the right, to see what one subagent did when translating %lld items.

The placeholder %lld will be replaced with a number at runtime. The string is varied by plural, which means in English, it says 'one item' or 'two items'. The subagent has also varied this string in Canadian French, allowing it to say 'un élément' or 'deux éléments', with different spellings. Other languages vary their plurals differently with more or fewer variations, Xcode makes sure subagents always know which variations are needed, no matter the language. There are a lot of strings left for the subagents to translate, so I'll take a quick break and have a snack.

Ok! It looks like the subagents completed their stack before I could finish mine.

Let's see how it looks when I run the app in Canadian French.

I'll select my scheme in the toolbar, edit the scheme, select Run, and navigate to Options.

Here, I can change the app's language to Canadian French for the next debug run. Now I'll build and run the app. That looks great, très bien! I can see I'm on the right track to make my app available to more people all around the world. Now, the app is currently using 'lieux d'intérêt' as the Canadian French translation for 'landmarks'. This is a great, well-understood translation! However, since I grew up learning Canadian French, I have a couple of stylistic ideas that will help my app's translations really shine. The term 'attraits', or 'attractions', is often used by the Canadian tourism industry in a similar way to how I'm using the word 'landmarks' in my app. I like the idea of using this more laid-back term, especially since it's very familiar to French-speaking Canadians. And for a little extra flair, I'll change the app name itself to 'Attraits phares' or 'Flagship attractions'. It's just as easy to make these changes as it was to add the original translations! I'll ask the agent to make the adjustments, and check back in, in a couple of minutes.

Great! Looking at some of the String Catalogs on the right, I can see the agent found all of the relevant strings and updated their translations, like the app name, and 'Draw a sketch of this landmark'. So far, I've covered how easy it is to get started with your first translations. However, it's just as easy to make translation a part of your workflow when adding new features to an app that's already localized. In fact, I've just had a great idea for another feature I want to add to my app. Let's build and localize it! Since this is a new feature, I'll start a new conversation.

I've asked the agent to add, and localize a fun label underneath the featured landmark, challenging people to discover all of the landmarks in the app. Once the feature is built, the agent will translate it into Canadian French. Looks like it's all done. And check out the String Catalogs on the right, the agent added plural variations for the new string in both English and Canadian French, and the Canadian French string correctly uses 'attraits' as the translation for 'landmarks'. This is really powerful! Without reading my previous conversation, while building a completely new feature, Xcode guided the agent to discover and reuse a translation for landmarks that it would not have chosen by default. It's this kind of consistency that helps make the app that much more cohesive in Canadian French! Now that I've got some translations in place, I'd like to talk about some techniques for reviewing and iterating on localized strings. Adding translations to your project is just one part of the story. It's important to make sure that everything is working as you expect at runtime in other languages. Different languages have different characteristics. For example, sentences in Canadian French are longer on average than their English counterparts. Since I just translated my new feature to Canadian French, I should make sure that all of the text still fits in my app's UI without truncating. I'll ask the coding agent to render the UI for my new feature in Canadian French and look for truncations.

Check out the preview on the right, looks like it spotted a problem! The text for my new feature is truncating before the end of the sentence. From here, I can investigate to see if this is simply a bug with my implementation, if this UI needs to be redesigned to accommodate the longer text, or if I should resort to asking the model for a shorter translation. I'll add that to my to-do list for later. You can use this technique to check for all kinds of issues that might crop up with different languages, including vertical clipping of text for tall languages like Thai, or incorrectly aligned views for right-to-left languages like Arabic. This tight feedback loop is extremely helpful for catching and fixing issues as you develop your features. To learn more about techniques and APIs for addressing issues around text layout, formatting, and more, watch "Build multilingual-ready apps" and "Get it right (to left)". Besides getting feedback from a coding agent, it's also very important to get feedback from other sources. As developers, one of our greatest strengths when using agents for programming is that we understand code. This means that we can tell if an agent is producing code that fits our needs, is missing some nuances, or is heading down the wrong path. That advantage disappears when using an agent to translate strings into languages we don't fluently speak. This is where tools like TestFlight really shine. Just as you'd ask people to test your exciting new features before you release them on the App Store, you should also ask native speakers to test your app in the languages you're adding. With TestFlight, people can easily share feedback containing suggestions, or screenshots of localization issues, so you can address them before you release your localized experience to the public. For example, I changed the translation for landmarks earlier because I speak Canadian French, but TestFlight would be a great place for me to receive similar suggestions for other languages! To learn more about collecting feedback for your app using TestFlight, check out the tech talk "Get Started with TestFlight". Before I wrap up, I'd like to mention a few tips and best practices that you can take advantage of to get the most out of the translation features in Xcode. Having a well-localized app means that all user-facing strings should be translated. Of course, this can only happen if your user-facing strings are localizable! As I mentioned near the beginning, SwiftUI code is localizable by default. In the rest of your code, you will likely need to use String(localized:) or other APIs to ensure your strings are localizable. For more details on the APIs you can use for localization, check out "Code-along: Explore localization with Xcode". Once you've made sure that all of your strings are localizable, consider the audience you're addressing with your app. For example, a banking app would likely use very different style and terminology than an app for children. By default, agents have access to Apple's translation expertise using language-specific style guides that ship in Xcode. However, they'll also respect any translation guidance you provide. For example, you can write a glossary containing specific translations you'd like to use for specific words, or a list of words that should always be left untranslated, like product names or trademarks, or even a plain-text description of the tone you wish your app to use. To provide this guidance, you can add a section about translation to the AGENTS.md file, or any other similar file, you may already have in your project. To avoid loading this additional context even when doing non-translation tasks, we recommend simply referring to a file called TRANSLATION.md, in which you write all of your translation guidance. The agent should only choose to read the document when working on translation-related tasks. Aside from translation guidance, there are a few other things to consider. Translating an app is a complex and long-running task, especially when ensuring translations use consistent terminology across the project. When thinking about which model to use, consider using one with a large context window that excels at completing extended requests, as these models are best suited for translation work. It's also important to note that some languages appear less frequently than others in the training data that most models use, which could cause agents to produce lower-quality translations for those languages. Some specific models may also perform better or worse at translating certain languages. Consult documentation from model providers for more information on the distribution of languages in their training data. And finally, if you're handling localizations exported from Xcode, you can check for the leveraged-mt state qualifier to understand which translations were provided by an agent. I encourage you to explore translating your app using agents in Xcode on your own. Try asking an agent to translate your app into a new language. Or, add a new feature, and translate it, into the languages your app already supports. Once you have translations, use the various agentic tools in Xcode to help you find and fix localization issues, and gather feedback from native speakers using tools such as TestFlight. When you have an idea of where it's needed, consider providing extra translation guidance to agents to help make sure all of your translations are great going forward. And finally, if you haven't already, check out "Xcode, agents, and you" to learn about all of the other amazing things you can do with agents in Xcode. Thank you for watching, and I hope these new translation features will help you reach new people all around the world with your apps. À bientôt!