Adopt a single, descriptive naming convention for all keys. This keeps translation work organized, helps teams understand the context, and makes the original value easy to locate at a glance for them. Use keys that represent the source string, its purpose, and the UI element it belongs to, not its translated value.
Structure keys in a clear hierarchy: feature, screen, and element, not flat lists. Use a format like home.forms.login.button or settings.profile.name to ensure a predictable structure that matches the UI. This approach is organized and helps ensure the key relates to the right portion of the interface, while staying consistent across other languages.
Maintain a single source of truth for translations in a centralized repository. This shared источник acts as the reference for all teams and helps coordinate updates across translation forms, strings, and languages. When a string changes, modify only the affected portion and retain the rest to minimize issues. Keep placeholders and variables intact in format strings to support reliable runtime substitution.
Guard strings and placeholders with explicit token names to avoid mismatches. Use a consistent format for tokens and ensure strings preserve meaning when variables are substituted. Always test with real values to verify match and tone across languages, and avoid duplicating keys for different contexts by reusing them only when the context is the same.
When adding new keys, attach context comments to explain usage and intent. This helps maintainers understand why a key exists and prevents creating multiple keys for similar strings. Use forms consistently for all input-related messages, and review keys during release cycles to catch issues instead of duplicating and creating inconsistencies.
Document conventions in a concise guide and maintain a changelog to simplify maintenance for teams and newcomers alike.
Key Design and POEditor Workflow
Recommendation: Use a namespaces-first naming convention and mirror it in POEditor. Each key uses module/namespace + descriptor, e.g., user.log_in.button, user.profile.name, dashboard.welcome.text. This keeps current strings and path consistent, supports multiple languages, and ensures the translation file will match code references. Place keys under a clear top-level namespace like app or module to simplify navigation in POEditor and in your codebase. Each key should include a short, meaningful name. Keep distinct names within different namespaces to avoid collisions.
POEditor workflow: export your code strings as a JSON with keys, import into POEditor, and review translations inline against the key's context. Create a dedicated documentation section that explains whats each key does, including allowed placeholders and how variable tokens map to runtime values. After translators finish, sync back to your app via API export or file import, then validate that every translation matches its key and renders correctly in the UI. This process helps developers and translators stay aligned.
Structure and maintenance: keep a stable place for keys and a consistent namespace hierarchy. Use names like module.section.key and avoid renaming existing keys when new text is added. For strings with variables, maintain the same placeholder names in code and in POEditor, e.g., {name} or {count}, and document the rules in the documentation so developers and localization specialists understand them. When you add a new language, reuse the existing namespaces to minimize boilerplate.
Practical tips: automate export/import with your build pipeline, start with a core set of keys per namespace, and add new keys gradually. Use the log_in key as a quick test to verify path consistency across environments. Keep a concise documentation entry for each namespace that explains whats the intended user impact and how to interpret the text in context. This approach reduces drift, improves searchability, and helps both user and developer understand the context of each string. Development teams will appreciate the streamlined process during development.
End result: a predictable mapping between code and translation assets, faster translations, and a maintainable process that scales as your product grows.
Adopt a consistent naming pattern: prefixes, namespaces, and separators
Define a single naming pattern and apply it everywhere: prefixes, namespaces, and a consistent separator scheme will streamline development, reduce translation drift, and save the team time when you manage strings across languages.
This approach gives clarity for current and future contributors, helps translators understand context, and keeps strings used in the blog and UI aligned with documentation in a shared folder structure.
- Prefixes: assign a short, stable prefix per domain, for example ui, blog, auth, or global. This helps you locate strings in existing folders and filename mappings, and it clarifies where a string belongs in the development workflow.
- Namespaces: nest one or more namespaces after the prefix to reflect feature or component scope, such as ui.login, blog.post, or blog.comment. If a paragraph or piece of copy appears in multiple places, a dedicated namespace prevents accidental reuse without context and makes maintainability easier for both developers and translators.
- Separators: pick a primary separator and stay consistent. A dot (.) between namespace levels is a common choice, while underscores (_) can separate multiword segments within a single level. Avoid spaces or mixed casing to prevent parsing issues in tooling and QA checks.
- Filename and folder alignment: mirror the key path in your folder names and in the filename that holds the resource. For example, a key like blog.post.title could live in folder blog/post and in a file named post_titles.json. This approach makes it easy to navigate, understand whats inside each file, and locate the current translation in documentation.
- Global vs local keys: reserve a global namespace for strings that apply across languages and contexts, and use local namespaces for feature or component strings. This reduces duplication and keeps translations coherent across languages in every release.
- Documentation and onboarding: maintain a concise guide that spells out the naming rules, with concrete examples and a mapping from keys to UI elements. Include whats allowed and whats not to prevent drift and to help translators work efficiently.
- Audit existing keys to map them to the new pattern, noting which folder and filename pairings will be affected.
- Plan a staged migration that updates keys, folders, and resource files without blocking ongoing development.
- Provide translators with context notes, glossaries, and screenshots to preserve meaning across languages.
- Enforce the pattern with a lightweight lint rule or CI check to ensure consistency throughout the codebase.
Keep keys descriptive and concise; encode context in the key structure
Start with a concrete recommendation: adopt a hierarchical naming convention that encodes context in the key path. For example: home.user.login.label; current page scope, and the element type. This approach clarifies where a string is used and what it refers to, reducing risk of duplication and misinterpretation.
Keep keys concise but descriptive; use design-driven patterns that reflect naming, home, user, label, and where the text appears (home, settings, dashboard). For instance, like home.dashboard.button.submit.label or home.user.profile.title. This structure helps developers collaborate across teams and gives management a clear convention to review, improving the current experience and consistency.
Abbreviations should be limited and documented; prefer explicit terms such as label, placeholder, message, and title. If abbreviations are used, include them in a shared glossary and apply them consistently. These jungle issues arise when a single key expands across modules, and they increase the risk for some localization partners. Including a glossary helps align across teams.
Structure keys by layers: home, page, component, element. Including context about where the string appears helps you avoid renaming cascades when pages change. Being explicit about context reduces churn and supports current experience by keeping the same depth and avoiding over-nested paths. Consider a maximum depth of four levels to keep readability high and tooling easy to enforce.
Process and governance: define who can add keys, require a naming review during code reviews, and enforce the convention with automated checks. Collaborate with design, developers, and product management to keep the dictionary stable and reduce risk during releases. Some teams benefit from a lightweight lint rule that flags keys that deviate from the pattern. Consider adding a short checklist to ensure every new key meets naming standards.
Maintenance tips: monitor for variable parts in keys and keep values out of the key itself. If a term grows, extend the path rather than stuffing long suffixes. This approach supports consistency, future-proofing, and easier onboarding for new developers and designers, improving the overall experience without introducing ambiguity.
Organize keys by feature modules and screens for scalable management
Organize keys by feature modules and screens using hierarchical namespaces that reflect the app structure. Place translations under modules/<feature>/<screen>/ and label files by current filename to provide quick context for maintenance.
Group keys by module first, then by screen, and within each screen keep keys in a small, self-contained set. Use a consistent form for placeholders and variables, e.g., modules.userProfile.editScreen.form.name, so a single change in a form field doesn't ripple across the jungle of keys. These groupings are hierarchical by design and reflect the UI flow, and they represent the shapes of the UI for translations.
Namespaces help avoid risk of collisions and confusion. Use precise names for modules and screens, avoid long, ambiguous keys, and prefer descriptive names over abbreviations unless documented. An outlined naming standard keeps everyone aware of where each translation sits, and below that standard you can find a glossary that explains abbreviations and conventions.
Keep translations within their place and ensure each key conveys intent. Keys should reflect the surface label or prompt, conveying the form’s purpose, not its content. Use variable placeholders for dynamic parts and avoid embedding content in keys; this provides consistency across translations and reduces maintenance work.
Maintenance becomes straightforward when you implement a checklist: organize by modules, stay within the place boundary, verify current filename mappings, and remove dead keys below a defined cadence. These steps reduce risk, streamline review, and allow some translators to work in parallel without conflicts.
To keep performance and tooling aligned, load translations module by module and keep per-file counts small. This grouping makes it easier to reuse translations across screens and to convey context to translators, while a focused file helps maintainers stay aware of progress.
In practice, document these conventions in a shared guide and reference it during reviews. The outcome is a clean, navigable map of translations that teams can trust as they add, revise, or remove keys within modules and screens.
Implement deprecation and cleanup: track usage and retire stale keys
Recommendation: Implement a formal deprecation workflow that tracks usage, marks keys as deprecated in the translation data, and retires stale keys after a defined window so they no longer impact new builds.
Track key usage across your projects: count translate() calls per key, record last access dates, and map references to teams and services. These metrics help you identify risk keys that are rarely used, and reveal issues that warrant a cleanup. Store the data in a lightweight report with a clear text field describing the context; this below plan lets you translate decisions quickly.
Define a deprecation policy: establish the scope, the responsible team, and the timeline. A typical window is 90 days, giving teams time to remove calls and implement a fallback. Instead of a single removal, consider a two-phase approach: announce deprecation in release notes, then remove in a follow-up version. This approach makes the process meaningful and avoids breaking the user experience.
Extend the key structure with explicit fields: status (active, deprecated, retired), retirementDate, reason, replacement, and notes. This outlined structure helps maintain clarity and consistent handling across the scope of your i18n data. Apply the convention across all projects to reduce similar issues as you scale and ensure the multiple structures remain aligned.
Automate cleanup: a scheduled sweep identifies keys with retirementDate reached or with zero usage over the last N days. Generate a report for the team, update the central catalog, and surface warnings in the UI for developers. If a key is retired, provide a clear fallback path to save the user experience, such as a fallback translation or a generic message. These safeguards save time and minimize disruption while maintaining quality.
Communicate in the team handbook: document the deprecation policy, the preferred wording for deprecation notes, and the process to replace keys. This experience helps new contributors understand the rules quickly and stay aligned with the established structure and convention.
Start small: focus on a portion of the catalog with low usage to observe the impact before expanding. This working approach reduces risk and helps your team stay confident about the changes. If a project faces breaking changes, coordinate with product and localization teams to plan the rollout.
Metrics to aim for: deprecate 5–10% of unused keys per quarter, verify there are no remaining references, and monitor text quality in translations after replacements. By staying consistent with these targets, you save time and maintain translation experience across languages.
These steps keep your translation structures healthy and reduce ongoing maintenance work over time. Maintaining a disciplined deprecation process also improves developer experience and helps teams stay focused on delivering meaningful localization.
Utilize POEditor features: context notes, comments, and pluralization handling
Being aware of the current needs, attach context notes to every string in POEditor, describing where it appears and which variable placeholders it uses. Place notes in the Context field for quick reading by translators. This approach will support maintenance and keeping translations aligned with the original meaning.
Use comments to discuss translations with management and other teammates. Link each comment to the related post or blog entry, and note the time when changes are made. This keeps them in the thread and makes it easy to track decisions.
Handle pluralization by configuring plural forms for languages that require them. Define all forms (singular and plural variants) and show the count variable clearly ({count}). This ensures translations reflect the current grammar while matching the numeric context.
Maintain a clean structure by grouping strings and placing them in folders. Use a consistent process to name folders and group related strings by feature or form. This improves maintenance and supports reuse of translations across posts and forms.
Keep awareness of the источник and terminology used in the source; reflect it in context notes to help translators match the intent in each place.
Process updates with a lightweight loop: after a post changes, read the context notes and verify plural rules, then request quick feedback from a reviewer. This keeps the workflow smooth and avoids drift.
Read current translations against the source to verify accuracy; maintain a short option set for editors to approve changes.
| Feature | How to use in POEditor | Benefit |
|---|---|---|
| Context notes | Attach concise context describing location, usage, and placeholders for each string. | Clear intent; guides translators to match the UI being implemented. |
| Comments | Use discussion threads to capture decisions, tag the right owner (management), and refer to related posts/blog entries; note the time of changes. | Traceable decisions; reduces back-and-forth during review. |
| Pluralization handling | Define all required forms for each language; include the count variable (e.g., {count}); test with sample numbers. | Accurate rendering across languages; avoids incorrect forms. |
| Organization (folders/grouping) | Organize by feature or module; keep related strings in the same folder and label clearly. | Faster maintenance; easier reuse of translations. |
| Source awareness (источник) | Record origin terminology and align context notes with the source text. | Terminology consistency; simpler updates later. |
