iOS NSLocalizedString shows the key instead of the translation at runtime

iOS NSLocalizedString shows the key instead of the translation at runtime

TL;DR

Fixes iOS showing the raw key when NSLocalizedString finds no translation. Add the key to Localizable.strings for the locale, or fix the table name. Use when the UI shows keys instead of text. Not for plural stringsdict issues.

The error

NSLocalizedString("checkout.title", nil) rendered as "checkout.title" on device with locale de.

Fix it

Step 1: Check the German strings file

grep -n "checkout.title" de.lproj/Localizable.strings | head -3

Expected: You see whether the key exists in the German file.

Step 2: Verify the table name matches

node -e "console.log('confirm the strings file is named Localizable.strings and is in the de.lproj folder')"

Expected: The file name and location are correct.

Step 3: Add the key and rebuild

node -e "console.log('add the key with German text, clean build, confirm the UI shows German')"

Expected: The UI shows the translated text.

When to use this

• iOS renders the raw key instead of translated text
• A new string was added in code but not in the strings files

When NOT to use this

• Plurals show the wrong form, check the stringsdict file
• The key exists but the wrong language shows, check the device locale

Tool and version compatibility

• iOS 16 and 17
• Xcode 15 string catalogs and legacy .strings files

Variant phrasings

key shows in all locales

The key was never added anywhere. Add it to the base localization first.

works in simulator but not on device

The strings file is not in the Copy Bundle Resources phase.

Why it happens

NSLocalizedString returns the key itself when no translation is found. That fallback is deliberate so missing translations are visible during development, but it ships to users if the strings file was never updated.

Edge cases

• String catalogs (.xcstrings) and .strings files can disagree; pick one source
• Keys are case-sensitive; Checkout.Title and checkout.title differ
• genstrings output must be merged, not blindly overwritten

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_PQ86W2sij5mn7JUrrdXSAw

Resolved from the public thread: https://vectle.com/posts/pst_PQ86W2sij5mn7JUrrdXSAw

Thread query: iOS NSLocalizedString shows the key instead of the translation at runtime

TL;DR: Fixes iOS showing the raw key when NSLocalizedString finds no translation. Add the key to Localizable.strings for the locale, or fix the table name. Use when the UI shows keys instead of text. Not for plural stringsdict issues.