Step-by-step localization workflow for developers

Creating a localization workflow might seem easy, but in reality, it can be quite challenging. Often, software developers tend to over-engineer the process, leading to unnecessary complexity and extra work. The sheer number of tools, options, and settings can be overwhelming, making it easy to get lost in the process.

In this article, I’ll share a step-by-step guide for setting up a localization workflow, focusing on web applications. However, the same principles can be applied to any software project. I will also share some tips and best practices I’ve learned over years of working with localization during my time at SimpleLocalize. You’ll learn the simplest way to synchronize your localization files between a translation editor and your local files. As a bonus, I’ll show you how to automate this process using SimpleLocalize automations.

This article is based on the latest SimpleLocalize CLI version (2.7.0+). If you’re using an older version, some commands may not work. See the CLI releases to update to the latest version.

Source translations as a separate file

One of the most life-changing tips for localization workflows is understanding that exported translation files should be treated as code-generated files and should not be edited manually. Some developers prefer to keep translations in Excel or CSV files, editing them manually. To accommodate this, we’ve added sorting options to the export function, but why overcomplicate the process?

The best approach for configuring a localization workflow is to keep the source translations in a separate file. It's your decision whether this file will serve as the source of truth or simply a file to push new keys and translations. Keeping it separate offers many benefits: you can format it as you like, include personal notes, and maintain it in the order that works for you.

Such approach will result in having two files with translations for the same language, but that's perfectly fine! In my example, I keep the source translations in a file called source.json in single-language-json format with English translations. Here you can check out the available file formats in SimpleLocalize.

Uploading source translations

Let’s begin by uploading the source translations to SimpleLocalize.

simplelocalize upload
  --apiKey YOUR_API_KEY
  --path ./i18n/source.json
  --format single-language-json
  --languageKey en-GB

Here, I specify the path to the source.json file in i18n directory, set the format to single-language-json, and use the language key en-GB for the source file. The language key is important because it tells the system which language the source file is in, ensuring translations are matched correctly in the editor.

Downloading generated translations

Downloading is simple—you just need to set the download path and specifying the format. I'll save the translations in the same directory we the source.json file but with different file names that will match the language key from the editor.

simplelocalize download
  --apiKey YOUR_API_KEY
  --path ./i18n/{lang}.json
  --format single-language-json

I've used {lang} placeholder so the CLI automatically includes the language key in the filename. You can customize this with any suffix, prefix, or even put the language key as part of the directory structure. The CLI will handle all these cases, creating directories if necessary.

Setting up a configuration file

To make the process easier, you can create a configuration file that will store all your CLI settings, so you don't have to type them out every time.

# simplelocalize.yml
uploadPath: ./i18n/source.json
uploadLanguageKey: en
uploadFileFormat: single-language-json

downloadPath: ./i18n/{lang}.json
downloadFileFormat: single-language-json

The API Key can be stored in the configuration file as apiKey property or as an environment variable. It's best practise to not store API Key in the configuration file, but as an environment variable.

export SIMPLELOCALIZE_API_KEY=YOUR_API_KEY

You can override the API Key (or any other parameter) by passing it as a CLI argument. The order of precedence for the CLI is: Command-line Parameter -> Configuration File -> Environment Variable (API Key only).

Now, your CLI commands can look like this:

# Upload source translations
simplelocalize upload

# Download translation files
simplelocalize download

Remember, that SimpleLocalize CLI looks for the configuration file in the current working directory. Head to the documentation to learn more about configuration file.

Source file as a source of truth

This approach may not be suitable for every project, but it’s worth mentioning. If you’re a solo developer or the only one responsible for translations, you can treat the source file as the source of truth.

Overwriting existing translations

If you decide to use source.json as the single source of truth, you might want to use the --overwrite parameter during the upload process. This updates translation texts in the editor with the translations from the source file without deleting any translations not present in the file.

# Upload source translations and overwrite existing translations
simplelocalize upload --overwrite

Deleting translations not present in the source file

If you want to delete translations that are not present in the source file, you can use the --delete parameter. This will remove any translation keys (along with their translations) that aren’t in the source file. However, this option can lead to data loss, so it’s generally not recommended. Instead, consider deleting old and unused translation keys through the editor. Check out our article on how to find and delete unused translation keys.

# Delete translations that are not present in the source file
simplelocalize upload --dlete

I’ve deliberately included a typo in the command to avoid accidental execution.

Automatically accept all source translations

If you want to mark all source translations as accepted, you can use --options MARK_AS_ACCEPTED parameter, which will automatically accept all translations that are uploaded.

simplelocalize upload --options MARK_AS_ACCEPTED

Automations for localization workflow

One of the great features of SimpleLocalize are no-code automations that you can configure in your project. It's a great option to speed up the localization workflow and make it more automated, especially if you are working in a small project.

I've configured one automation that will run every time I change or add new translations via CLI. That means the automation will run every time I upload source.json, but the automation will run only for changed or added translations. It's a great way to speed up the process of translating new keys.

In the video, you can see how the automation is triggered after uploading the source file with changed translations for ACHIVEMENTS and ACTIVITY.COMMENT_ADD. The system recognizes the changes and triggers the automation that automatically translates the updated keys into other languages.

It's like magic! ✨ You can write in 5 languages simultaneously without any extra effort beyond uploading a file with source translations. Isn’t that amazing?

Conclusion

In this article, I’ve walked you through setting up a localization workflow for developers. I’ve shared valuable tips and best practices learned over the years, and as a bonus, I’ve shown you how to automate the process using SimpleLocalize automations to instantly translate new keys after uploading the source file.