Localization Best Practices for Developers
Localization is no longer just a finishing touch; it’s a core part of building global products. A well-localized application improves accessibility, enhances user experience, and builds trust across cultures and markets.
In this article, we’ll explore the best practices developers should follow to make localization scalable, maintainable, and efficient. We’ll also see how Gleef can support this process by centralizing translation workflows, keeping keys organized, and automating translations and key creation.
What Is Localization
Localization is the process of adapting a product, app, or website for different languages, regions, and cultural contexts.
For developers, localization means preparing code, UI, and data to support multiple languages without breaking functionality or design. It involves managing translation keys, using consistent naming conventions, and organizing localization files such as JSON or YAML to make the process scalable and efficient.
For product teams, localization is a continuous workflow that connects design, development, and translation. Tools like the Gleef Figma plugin help translate Figma designs directly in context, while the Gleef CLI and Gleef Studio streamline synchronization and review. Together, they make localization an integrated part of modern software development, not an afterthought.
1. Planning and Strategy
The first best practice to keep in mind isn’t strictly technical, it’s organizational. It may seem obvious, but having a clear plan from the start is essential for successful localization.
Localization should be planned from the very beginning. Waiting until the end often leads to hard-coded text, disorganized keys, and UIs that break when longer languages are added. By defining early how strings will be stored, how the interface will adapt, and how translations will be integrated into the workflow, developers can prevent unnecessary rework and ensure the product is ready to scale across markets.
Some questions to consider during planning include:
• Who will own the creation and naming of localization keys to ensure consistency?
• What process will we use to review keys before they are integrated into the product?
• How will quality assurance be implemented to catch translation or formatting issues early?
• At which point in the workflow should translations be added, directly in Figma, in code, or in a centralized platform?
• How can we make the localization process collaborative across designers, developers, and translators?
2. Translation Keys and Context for Translators
Once localization is part of the development plan, the next step is defining how to structure translation keys and provide sufficient context for translators to create and use them correctly.
Abstract keys (e.g., user.welcome.title) are language-independent and make scaling or refactoring easier. Natural keys (“Welcome to our app”) tie translations too closely to the source language. Use clear, descriptive, and consistent naming conventions like auth.login.button or errors.emailInvalid instead of vague names such as btn1 or msg2. Group related keys with namespaces or prefixes and avoid unnecessary nesting.
Context is crucial. Translators and product teams need to understand the specifics of your app, where and how texts are used, their purpose and function, and the intended tone, whether formal or informal. Indicate where the text appears, such as a button, title, or tooltip. Context-rich keys like profile.avatar.uploadError ensure translations are accurate and consistent.
Gleef Figma Plugin enhances this step by analyzing not only the text but also its context in the design, for example whether it’s a button, label, or title, and generating meaningful keys automatically. This ensures consistency and reduces ambiguity for translators.
3. File Management and Backend/Frontend Strategies
A well-structured file system is essential for scalable localization. Each language should have its own file, ideally organized by feature or platform. Use consistent naming, UTF-8 encoding, and clear folder structures to make files easy to navigate and maintain.
File formats depend on the tech stack: JSON is common for web apps, YAML for Ruby on Rails, XLIFF for Angular, XML for Android or enterprise systems, and CSV for translator-friendly spreadsheets (often requiring conversion before integration).
The file structure directly affects your localization strategy:
- Frontend-only: JSON or YAML files loaded on the client allow dynamic language switching at runtime. Ideal for SPAs and React-based apps, but large bundles can affect performance.
- Backend-driven: Pages are localized server-side using formats like XLIFF, PO, or XML. This ensures consistency and SEO benefits but may add server overhead and slow deployments.
- Hybrid approach: Static UI translations remain on the frontend, while dynamic or user-generated content is fetched via backend APIs, often backed by YAML, XML, or database-stored translations. This balances performance and scalability but requires good synchronization.
Gleef CLI automates file management, synchronizing translation files with your code repository, handling push/pull of keys, and integrating with CI/CD pipelines to maintain consistency across platforms.
4. Synchronizing Translations with the Code Repository
Keeping translation files in sync with the codebase is one of the most common and critical tasks for developers. Translation files should be treated like any other source code, committed to version control, and updated alongside relevant changes to prevent runtime errors and missing keys.
Manual export/import between a translation management system and a Git repository, or pull requests for every translator update, is tedious and error-prone. Translators typically do not work directly with Git, so automation is essential. CI pipelines or Gleef CLI can pull new translations from the translation management system, validate them, and push updates to the repository. Integration with GitHub, GitLab, or Bitbucket allows automated commits or pull requests whenever translations are updated.
This automation reduces errors, saves time, and keeps the development, translation, and CI/CD workflows aligned. It’s important to note that some localization integrations may require full access to your repository. Before enabling them, check your security policies carefully, as giving external tools broad permissions could conflict with internal security guidelines.
5. Working with Pluralization and Complex Language Rules
Pluralization is one of the trickiest aspects of localization. Different languages have different rules: English has two forms, Russian four, Arabic six, and Polish three or more depending on the number. Some languages like Chinese or Japanese do not have distinct plural forms; context determines whether a noun is singular or plural.
Other complexities include text direction (RTL), gendered forms, and variable ordering in sentences. Arabic or Hebrew require right-to-left layouts, while German or French may reorder placeholders. Numbers, dates, and currencies also need locale-specific formatting to avoid errors.
Pluralization also extends to ordinal numbers, which vary across languages. In English, for example, we use “1st”, “2nd”, “3rd”, “4th”, and so on, but other languages have different rules and suffixes, affecting translation and display.
To handle these complexities consistently, it’s recommended to use standardized formats and libraries such as ICU MessageFormat, i18next, or FormatJS. Include all plural forms required by each language, even if not every form appears in your source content. Avoid hardcoding rules; rely on tools that automatically handle pluralization, ordinal forms, and other language-specific rules.
Standardizing plural keys, supporting RTL layouts, and properly formatting dynamic content ensures translations are accurate and the UI remains intact. Automation and structured key management reduce errors and simplify ongoing maintenance.
6. Previewing Translations in the Design Stage
Previewing translations early helps catch layout and usability issues before development. Languages differ in text length, word order, and reading direction, so layouts that work in English may break in German, Arabic, or Hebrew.
Developers and designers should collaborate using tools that support multi-language previews, such as Figma or Sketch integrated with a translation management system. Gleef Figma Plugin allows teams to preview translations directly in design frames, testing how buttons, labels, and text blocks fit, and how RTL languages render. Early previewing reduces costly rework, ensures consistent UI/UX, and aligns translators, designers, and developers on the final interface.
7. How Gleef Supports Best Practices
- Gleef Figma Plugin: Generates context-rich keys with AI, prevents duplicates, and previews translations in design frames. Helps designers and developers plan localization from the start.
- Gleef CLI: Automates file synchronization, push/pull of keys, integrates with GitHub/GitLab/Bitbucket, and supports CI/CD pipelines. Ensures file management and backend/frontend strategies are applied consistently.
- Gleef Studio: Centralized platform for developers, designers, and translators. Manages review workflows, tracks progress, and synchronizes changes with CLI and Figma Plugin.
Together, these tools create a seamless workflow that connects design, development, and translation, making best practices easy to follow and maintain.
