i18n Key Management Best Practices for Teams

i18n Key Management Best Practices

Managing translation keys at scale requires processes and tooling beyond just naming conventions. These best practices help teams maintain clean, consistent, and complete translation files.

1. Establish a Key Style Guide

Document your conventions in a shared style guide:

• Naming convention (dot notation, snake_case, camelCase)
• Maximum key depth (e.g., 4 levels)
• Namespace strategy (per-page, per-feature, per-component)
• Required key categories (buttons, labels, errors, status)
• Plural key format (library-specific)
• Interpolation variable naming ({{userName}} vs {user_name})

2. Use a Translation Management System (TMS)

Popular TMS platforms for developer teams:

Platform	Strengths
Crowdin	GitHub/GitLab integration, CLI, in-context editing
Lokalise	Developer-friendly API, Figma plugin, webhooks
Phrase	Enterprise features, plural handling, branching
Weblate	Open source, self-hostable, git-native
POEditor	Simple UI, good free tier, API

A TMS automates the workflow: developer adds key -> translator gets notified -> translation syncs back to repo.

3. Detect Unused Keys

Over time, keys accumulate that are no longer referenced in code. Use tools to find them:

• i18next-parser -- scans code for t() calls and compares with translation files
• i18n-unused -- finds keys in JSON/YAML that no code references
• Custom scripts -- grep for key strings across the codebase

4. Lint Translation Keys

Add key linting to your CI pipeline:

• Check for missing keys (key exists in English but not in Japanese)
• Check for extra keys (key exists in Japanese but not in English)
• Validate interpolation variables match across locales
• Enforce naming convention rules
• Detect duplicate keys

5. Continuous Localization Workflow

Developer adds English string
        |
    Push to git
        |
    TMS detects new keys
        |
    Translators are notified
        |
    Translations reviewed & approved
        |
    TMS pushes translations back to git
        |
    CI validates completeness
        |
    Deploy

6. Key Freezing for Releases

Before a release, freeze the translation keys:

1. Extract all keys from the codebase
2. Send to translators with a deadline
3. No new keys after the freeze date
4. Validate 100% translation coverage before release
5. Document new/changed keys in release notes

7. Context for Translators

Keys alone are not enough. Provide context:

• Screenshots -- show where the string appears in the UI
• Description -- explain the context in the TMS
• Character limits -- specify maximum length for UI constraints
• Placeholders -- document what each interpolation variable contains