When managing localization at scale, it’s easy for small misalignments in workflow to result in significant coordination issues. One such issue we encountered was a series of duplicated keys and confusing merge conflicts—errors we later tracked back to a problem with how our Crowdin sync was configured. While this initially disrupted our release cadence, it resulted in a long-term improvement: adopting a new branching and context-driven workflow that prevented further localization collisions in the future.
TLDR
A misconfigured Crowdin sync caused duplicated translation keys and multiple merge conflicts across branches. The root cause was linked to how Crowdin injected translations directly into the main branch, bypassing proper context segregation. To solve this, we introduced a new branching model combined with a context-aware workflow that aligned developers, translators, and reviewers. This drastically reduced key duplication and improved our i18n release stability.
The Problem: Unexpected Key Duplication and Merge Chaos
Our team relies heavily on Crowdin for managing translation of all user-facing strings across several products. Earlier, we had configured Crowdin to automatically push translated strings into our Git repository. At first glance, this seemed efficient—updates happened quickly, and developers didn’t have to do much manual work. But as our project scaled, things started to go wrong.
Suddenly, we noticed an unusual pattern. Files in our `/locales` directory held multiple strings with identical keys, each pointing to different values. At the same time, Git merge conflicts increased, often in codebases untouched by the teams that ran into these issues. Further inspection revealed that Crowdin’s push was integrating localized keys directly into our default branch—regardless of which feature or release branch the original string originated from.
We identified three major issues:
- Key duplication: Developers unknowingly created keys that already existed but had been altered or translated downstream in Crowdin.
- Merge conflicts: Translations committed by Crowdin clashed with in-progress development work on other branches.
- Context loss: Translators received little or no info about where strings were used, resulting in confusing or misleading translations.
Digging Deeper: Root Cause Analysis
To uncover what went wrong, our DevOps and i18n teams collaborated to audit the Crowdin integration pipeline. We found that our Crowdin configuration used direct sync on the default branch. Any time translators updated a string, the system retroactively committed changes directly into the main branch, even if that string had originated in a feature branch. This disconnected the intentions of the developer from the changes made by translators.
The absence of scoped translation branches meant that multiple features introduced identical or near-identical i18n keys. Since Crowdin treated all keys as part of a monolithic project, naming collisions became inevitable. Furthermore, once these changes were committed into the main branch by Crowdin, every feature branch needed to merge them—whether or not their changes were relevant. This turned the elegant promise of automation into chaos at scale.
The Turning Point: Workflow Reimagined
It became evident that our setup lacked a clear separation of concerns between development and localization. We were forcing a real-time translation cycle onto an asynchronous development process. The fix was two-fold:
- Branch-based Translation Integration
- Contextual Metadata and Translation Scoping
1. Setting Up a Branch-Centric Localization Flow
We started by redefining how we integrated Crowdin into our Git workflow. Rather than pushing all translations into the main branch, we reconfigured Crowdin to work with a feature-branch aligned model. Each development branch would generate its own localization context and push only relevant string keys to Crowdin.
Here’s what this meant in practice:
- Each new feature branch included an `i18n-branch.json` manifest mapping new keys.
- Crowdin only pulled strings from and pushed localized versions to that particular branch.
- Each feature was isolated in its translations, preventing inadvertent cross-contamination of string keys across unrelated modules.
This adjustment significantly reduced merge conflicts. Plus, it introduced natural boundaries for translators to work within.
2. Embedding Context Into the Workflow
A translation is only as good as the context provided. Previously, translators saw keys like `button.save` or `modal.warning.message` with no idea where or how they appeared in-app. Without knowing whether a message was a warning to users or internal debug copy, translations often missed the mark.
To address that, we overhauled our key creation process to include contextual metadata. Developers were required to append context tags to each new translation entry, such as:
"button.save": {
"message": "Save",
"context": "Primary action button in edit profile form"
}
Additionally, these contexts were rendered inside Crowdin’s In-Context preview system, letting translators view the string in its interface environment. As a result, we saw reduced variation in tone and better alignment across languages. This also enabled linguistic QA teams to isolate low-confidence translations efficiently.
The Results: Measurable Improvements Across the Stack
Once the workflow changes were fully implemented, we tracked several key metrics across our frontend pipeline and localization operations:
- 80% reduction in merge conflicts involving `locales` files.
- Zero key duplication in committed JSON files over a three-month release cycle.
- 35% decrease in translator revision cycles due to improved context and clarity.
- Improved UX consistency in international markets resulting from aligned tone and format across translations.
Lessons Learned and Team Alignment
The most crucial insight from this incident was that localization can’t be treated as an afterthought. Just as branches and code reviews ensure software quality, a well-defined i18n process ensures translation integrity. Our team learned to treat translators not as post-process workers but as collaborators who need the same level of context and clarity as any QA engineer or developer.
Furthermore, by embedding ownership into branches and contextual metadata, we built guardrails that allowed scaling without deterioration in quality. And perhaps most importantly, it reminded us all that just because a platform allows automation doesn’t mean every workflow should be automated without strategic consideration.
Best Practices Going Forward
If your team is building multilingual products and using a tool like Crowdin, here are several steps you can take to avoid the mistakes we made:
- Always enable branch-level synchronization instead of committing to main.
- Establish conventions for key uniqueness and naming per module or feature area.
- Require developers to write clear context descriptions when submitting new i18n keys.
- Utilize Crowdin’s In-Context tools to preview strings as they appear in the UI.
- Conduct periodic translation QA audits to detect redundant or conflicting keys early.
Conclusion
While the duplicated keys and localization collisions initially felt like a setback, they led to a much more robust and scalable system. By adopting a branching model aligned with development workflows and embedding context at every level, our localization pipeline is now more predictable, precise, and collaborative.
For teams seeking to mature their i18n processes, remember: translations are a living part of your UI. They deserve the same rigor, structure, and version control as your application code.
