Key renames can accidentally hide stale translations. Use this workflow to keep behavior predictable.
When To Use This Guide
Use this guide during refactors where string identifiers are renamed but app copy may stay the same.
Typical scenarios:
- Namespacing cleanup in iOS XCStrings keys.
- Unifying key naming conventions across platforms.
- Removing legacy key prefixes.
Recommended Workflow
- Enable Auto Retranslate on Key Rename in project settings.
- Rename key identifiers in source files.
- Run sync and review rows marked
NeedsReview. - Confirm unchanged values were preserved and changed content was requeued.
What String Catalog Does
- Detects removed and added keys in the same sync.
- Compares key content patterns to identify likely rename carry-over.
- Requeues non-base rows when rename carry-over is detected and requires review.
Expected Result
When a rename carries forward the same meaning, translations can be preserved or minimally re-reviewed instead of being lost.
When meaning changes, rows are pushed back into review or retranslation so outdated app localization does not ship silently.
Best Practice
Bundle key renames in dedicated PRs to make review intent obvious.
Common Mistakes
- Renaming keys and rewriting copy in the same commit without clear review notes.
- Expecting rename logic to recover intentionally deleted keys.
- Skipping post-sync review for rows marked
NeedsReview.