Translating Your App

This guide covers the complete workflow for translating your app with XCStrings Translator.

Opening Your Project#

1. Launch XCStrings Translator
2. Click Open Project and select your Xcode project folder
3. Your .xcstrings files appear in the left sidebar

The app scans up to 3 levels deep for String Catalog files.

Translating Strings#

Translate Selected:

1. Click on strings to select them (Cmd + click for multiple)
2. Press Cmd + T or click the Translate button

Translate All Untranslated:

1. Press Cmd + Shift + T
2. All strings with "new" state are processed

Adding Languages in Xcode#

To add a new language to your app:

1. Open your project in Xcode
2. Select your project in the navigator
3. Select the project (not a target)
4. Go to the Info tab
5. Under Localizations, click +
6. Choose a language from the list

Xcode adds the language to all String Catalogs with "state": "new" for each string. Then open your project in XCStrings Translator to translate them.

For more information, see Apple's documentation on localizing your app.

Adding Context with Comments#

Good translations need context. Add comments in your Swift code:

// SwiftUI
Text("Post", comment: "Button to publish a new blog entry")

// String(localized:)
String(localized: "Post", comment: "Noun: A blog post, not the verb")

Without the comment, the AI might translate "Post" as a fence post instead of a blog post.

Writing Effective Comments#

Do:

• Explain what the UI element is (button, title, error message)
• Clarify ambiguous words
• Mention character limits if relevant
• Note if something shouldn't be translated

Text("Save", comment: "Button to save document changes")
Text("iPhone", comment: "Product name, do not translate")

Don't:

• Repeat the string value: comment: "Save"
• Add implementation details: comment: "Calls saveDocument()"

How Xcode Extracts Strings#

When you build your project, Xcode:

1. Extracts strings from Text(), String(localized:), and other APIs
2. Adds new keys with state "new"
3. Marks strings as "stale" if the source text changes
4. Preserves existing translations

Review and Save#

After translation:

1. Double-click any string to edit manually
2. Review translations marked as "needs_review"
3. Press Cmd + S to save

Changes are written directly to your .xcstrings file, so you can commit them with git.

Keyboard Shortcuts#

Next Steps#

• Learn about plural rules for handling "1 item" vs "5 items"
• Set up custom prompts for better translation quality
• Understand translation states to manage your workflow