Internationalization (i18n) is often treated as optional. However, as business expand globally, product team may face a significant challenge: how to implement a comprehensive i18n system for a nearly mature product?

This article record how our team addressed the challenge, particularly when dealing with 400+ files and inconsistent translation among team members.

Challenges

There’s many i18n paid service in the market such as Phrase, Lokalise etc, which provide complete translation management systems. However, our company did not have the budget at the time. We chose a self-built solution, and here are some challenges we faced:

  1. Scale: Over 400 files needed to be translated, containing large amount of hardcoded text
  2. Consistency: Different team members had their own understandings to translate.
  3. Develop Experience: Establishing a repetitive yet essential process of i18n implementation.
  4. Quality: Ensuring no new bugs was introduced after translation.

Scale

To be honest, it’s the biggest challenge. Translating over 400 files is a boring and overwhelming task, especially while still developing other features.

To tackle this, we came up a strategy called Daily Tasks. Three of us dedicated a small amount of time (around 30 mins) daily to translate. It’s a makeshift method but it works, end up finishing within a quarter.

The “small steps” approach significantly reduced our psychological burden. By breaking down the mountain of work into manageable daily chunks, we maintained steady progress without burning out.

Consistency

At first, we underestimated the task and thought easy work didn’t need standards. It turns out that when it comes to teamwork, a lack of clear standards leads to chaos. So we invested time to made a detailed translation guidelines.

  1. Namespace: Since we used server-side loading for individual pages, we decided to divided namespaces by page.
  2. Limited nesting levels: We limited nesting to no more than two levels to avoid overly complex structures, different categorization logic and long text in code base.
  3. Context-orient naming: Keys used the relative context for naming, instead of translated the content directly, since business requirements often chang. ex: 確認取消課程 will be unenrollCourse.title instead of unenrollCourse.cancel_confirmation_question

We also established naming style conventions, file structure standards, and more in our GitHub Wiki to ensure new team members could understand and follow them.

These standards not only simplified the developers’ work approach but also significantly reduced conflicts between different ways of thinking.

Develop Experience

After establishing guideline, we still faced issues with typos and development efficiency. Initially, we attempted to use TypeScript for i18n but found that tons of namespaces created a large type tree, leading to slow compilation and a frustrating developer experience.

After research, we chose the VS Code i18n Ally extension, which greatly transformed our workflow. It provided:

  1. Real-time Preview: Developers could see the actual content of translations directly without switching files
  2. Missing Translation Alerts: Automatically flagged untranslated strings
  3. Duplicate Key Detection: Avoided creating duplicate translation keys
  4. One-Click Navigation: Quickly navigated to translation definition locations

This tool increased our translation efficiency, and almost finished the i18n implement task within few weeks.

Quality and Maintain

However, after completing the translation, we continued to receive bug reports. While i18n Ally helped catch basic bugs like typo or wrong key in single file, we still struggled with errors spread across multiple files or cases where keys were implemented in various locations.It’s hard to trace all of the careless mistake.

To systematically address these issues, I bring up the Typescript may still needed. To avoid poor develop experience caused by slow compile time, we decided to introduce Typescript into our CI/CD pipeline.

Since I wanted to learn CI/CD, my team and manager gave me the opportunity to lead this refactor initiative. Here’s the steps I took:

  1. Test Locally: create a i18next.d.ts base on official document, and checked it worksed as expected on local environment.
  2. Bash Shell Script: Wrote(and learned) a bash script to create i18next.d.ts in a specific file with eslint & prettier, make sure the script works successfully.
  3. CircleCi YAML: Added the commands in circleCI YAML file, and tested on CI/CD pipeline.

After deploying this feature, i18n translation bugs stop appearing completely.

Results and Lessons Learned

It’s a major feature that challenged our development team and provided valuable insights. It taught me how to balance technology choices between business needs and developer efficiency. I also learned a lot:

  1. First Standardize, Then Execute: Establishing clear guideline is necessary.
  2. Tool Empowerment: The right tools could greatly increase efficiency, make overwhelming tasks more manageable.
  3. Never Trust Human: If a process can be automated, automate it. CI/CD integration ensured long-term quality maintenance.

Through this process, I not only improved my technical knowledge but more importantly gave me a better insight into not only caring about developing product features but also improving the development experience, which can make a huge difference for the team.