iOS Strings

This tutorial connects a Swift app’s Localizable.strings files to Hyperlocalise Cloud. The CLI preserves keys, comments, and file formatting while replacing translated values.

Prerequisites

You need:

an iOS project that uses .strings resources;
the Hyperlocalise CLI;
a Cloud project with en-US as source and fr-FR and de-DE as targets; and
HYPERLOCALISE_API_KEY and HYPERLOCALISE_PROJECT_ID in your environment.

The example uses:

ios/App/
├── en-US.lproj/Localizable.strings
├── fr-FR.lproj/Localizable.strings
└── de-DE.lproj/Localizable.strings

Add these folders to the app target in Xcode so each file is included in the built bundle.

1. Move visible copy into `Localizable.strings`

Create ios/App/en-US.lproj/Localizable.strings:

/* Navigation title on the saved filters screen */
"filters.title" = "Saved filters";

/* Confirmation shown after the user saves a filter. %@ is the filter name. */
"filters.saved.confirmation" = "Saved “%@”";

/* Button that removes the selected saved filter */
"filters.delete.action" = "Delete filter";

Use stable semantic keys in Swift:

let title = String(localized: "filters.title")

let confirmation = String(
    format: String(localized: "filters.saved.confirmation"),
    filterName
)

Descriptions beside each entry give reviewers the context that short UI strings lack. Keep placeholder meaning in the comment.

2. Map the locale folders

Create i18n.yml at the repository root:

locales:
  source: en-US
  targets:
    - fr-FR
    - de-DE

buckets:
  ios:
    files:
      - from: ios/App/{{source}}.lproj/Localizable.strings
        to: ios/App/{{target}}.lproj/Localizable.strings

hyperlocalise:
  project_id_env: HYPERLOCALISE_PROJECT_ID
  api_base_url: https://hyperlocalise.com/api
  api_key_env: HYPERLOCALISE_API_KEY

If your project uses language-only folders such as fr.lproj, use target locale names that match those folders or map separate buckets to the exact paths your Xcode project expects.

3. Check the source pull request

Before merge, verify the upload plan:

hl sync push --dry-run

Also run your normal Xcode build and tests. A source pull request should confirm:

every localized lookup has a source entry;
duplicate keys do not exist;
the .strings file uses valid quoted key/value syntax; and
placeholders such as %@, %d, and positional variants remain explicit.

Do not copy English values into target files as placeholders. A target that equals the source can look complete while remaining untranslated.

4. Push source strings

After the source pull request merges:

hl sync push

The command uploads en-US.lproj/Localizable.strings. It does not start translation. Use a Source upload automation or create a request in Cloud.

5. Review iOS strings in Cloud

In Content Editor, check:

comments that explain the screen and control;
%@, %d, or positional placeholders;
terminology used in navigation and buttons;
punctuation and smart quotes; and
likely expansion in compact layouts.

Attach a screenshot when a label has limited width. Approve each locale after linguistic review.

6. Pull translated `.strings` files

Run:

hl sync pull
hl check --bucket ios --quiet

Hyperlocalise writes:

ios/App/fr-FR.lproj/Localizable.strings
ios/App/de-DE.lproj/Localizable.strings

It keeps the source file’s comments, keys, ordering, and key/value formatting while replacing value literals. Open the result as a translation pull request. Review the diff and run the app in every target language.

7. Test in Xcode

For each target locale:

Edit the scheme.
Under Run → Options, set App Language.
Open the translated screens.
Exercise values that substitute %@ and numeric placeholders.
Check compact devices and accessibility text sizes.

Add a test that catches a missing key:

func testSavedFiltersTitleIsLocalized() {
    let bundle = Bundle(for: AppDelegate.self)
    let value = bundle.localizedString(
        forKey: "filters.title",
        value: nil,
        table: nil
    )

    XCTAssertNotEqual(value, "filters.title")
}

Plurals with `.stringsdict`

Use .stringsdict when the app already depends on Apple’s legacy plural format. Add a second mapping:

buckets:
  ios:
    files:
      - from: ios/App/{{source}}.lproj/Localizable.strings
        to: ios/App/{{target}}.lproj/Localizable.strings
      - from: ios/App/{{source}}.lproj/Localizable.stringsdict
        to: ios/App/{{target}}.lproj/Localizable.stringsdict

Hyperlocalise treats .stringsdict as an already-segmented format. Keep plural variable names and format specifiers stable, then test 0, 1, and several plural values in the app. If you use modern Xcode String Catalogs instead, map .xcstrings files as described in i18n configuration.

Troubleshooting

Xcode shows the key instead of a translation

Confirm the target .lproj folder belongs to the app target, the filename is Localizable.strings, and the Swift lookup uses the exact key.

Placeholder checks fail

Restore the source placeholder names and positions in the target value. Positional placeholders are safer when a language needs to reorder arguments.

Pull skips a locale

Confirm that locale has translations in the selected Cloud project. Run hl sync pull --dry-run and compare the resolved path with the Xcode localization folder.

Getting started

Tutorials

Workspace

Connect

API

Contributing

Prerequisites

1. Move visible copy into `Localizable.strings`

2. Map the locale folders

3. Check the source pull request

4. Push source strings

5. Review iOS strings in Cloud

6. Pull translated `.strings` files

7. Test in Xcode

Plurals with `.stringsdict`

Troubleshooting

Xcode shows the key instead of a translation

Placeholder checks fail

Pull skips a locale

Next

​Prerequisites

​1. Move visible copy into Localizable.strings

​2. Map the locale folders

​3. Check the source pull request

​4. Push source strings

​5. Review iOS strings in Cloud

​6. Pull translated .strings files

​7. Test in Xcode

​Plurals with .stringsdict

​Troubleshooting

​Xcode shows the key instead of a translation

​Placeholder checks fail

​Pull skips a locale

​Next

Prerequisites

1. Move visible copy into `Localizable.strings`

2. Map the locale folders

3. Check the source pull request

4. Push source strings

5. Review iOS strings in Cloud

6. Pull translated `.strings` files

7. Test in Xcode

Plurals with `.stringsdict`

Troubleshooting

Xcode shows the key instead of a translation

Placeholder checks fail

Pull skips a locale

Next