As your application grows to support multiple languages, manually managing localization becomes increasingly complex. Extracting source keys, coordinating translations, and integrating updates can quickly lead to inefficiencies, delays, and errors.

Integrating localization workflows into your CI/CD pipelines provides a scalable and automated solution. This approach reduces manual overhead, keeps translations aligned with code changes, and streamlines the process of delivering localized versions alongside product updates. 💪

This guide will show you how to integrate localization into your CI/CD pipelines. You'll learn how to automate tasks like uploading source keys and downloading translations while managing multilingual projects with CI/CD platforms such as GitHub Actions, Bitbucket Pipelines, and GitLab CI.

🏄‍♂️ For more tips on automated localization, check out our other guides here

📋 Prerequisites 🔗

To implement this localization workflow, you'll need a tool that integrates seamlessly with CI/CD pipelines. This guide uses Localazy CLI, a command-line tool for efficiently managing multilingual localization projects.

With Localazy, you can:

  • ⚡️ Automate localization tasks, such as uploading source keys and downloading translations.
  • 📩 Trigger localization updates directly from your CI/CD pipeline, keeping translations synchronized with your codebase.
  • 👥 Manage distributed teams effectively using features like branching, releases, and role-based workflows.

Workflow outline 🔗

Here's an outline of the localization workflow you'll implement:

  • You'll work with three branches: workflow-demo, dev, and main.
  • Source keys are created in feature branches (e.g., workflow-demo) and merged into the dev branch via pull requests.
  • Your CI/CD pipeline uploads the source keys to Localazy when you merge into the dev branch.
  • Translators translate source keys in the Localazy dashboard.
  • When the product is ready to go live, changes are merged from dev to main, triggering the download of automatic translations.

Now that you understand the workflow, let's proceed with the initial setup.

🖇️ Initial setup 🔗

This guide uses a Vue.js application that displays the landing page of a fictional travel company called Worldwide Wonders. You'll localize this English website using Localazy. To get started, we'll follow these steps:

  1. Fork the repository: When forking, uncheck "Copy the mainbranch only" to include all branches.
  2. Clone your fork: Clone your forked repository to your local machine.
  3. Switch branches: Checkout to the workflow-demo branch using git checkout workflow-demo.
  4. git checkout workflow-demo.
  5. Install dependencies: Run npm install to install the required packages.
  6. Install the Localazy CLI: Now follow the installation setup specific to your operating system.
  7. Create a Localazy account: Sign up for a Localazy account or log in if you already have one. Then, set up a new organization and create a project.
  8. Generate access keys: Navigate to your project and go to Project Settings → Access keys to obtain your readKey and writeKey. Save these keys, as you will use them later during the CI/CD pipeline setup.
article-image
Remember to save your read and write keys – you'll need them later.

Localazy CLI setup 🔗

Localazy provides two CLI commands for managing your localization project workflows. These commands use the readKey and writeKey secrets from your project to determine where to store and retrieve data:

  • localazy upload: Uploads the source keys to the Localazy dashboard using the writeKey.
  • localazy download: Downloads translations using the readKey.

Open your code editor and create a localazy.json file in your project's root directory. This file stores the configuration for the upload and download commands. Paste the following content into the file:

{
	"upload": {
		"type": "json",
		"files": "src/assets/locales/en.json"
	},
	"download": {
		"files": "src/assets/locales/${lang}.json"
	}
}

In the snippet above, the upload section specifies the file type and source key path, while the download section specifies the download path with a special placeholder, $lang, indicating the file format.

⚠️ This is a basic example of a configuration file for Localazy CLI; check out the documentation for a more advanced setup

Next, create a localazy.keys.json file in your project root and paste the below content into it, replacing the placeholders with your project keys:

{
	"readKey": "<your-read-key>",
	"writeKey": "<your-write-key>"
}

This file stores your project's authentication keys. It's already listed in .gitignore to prevent accidental commits. In the next section, you'll use this file to simulate the upload process locally.

The repository contains the English source keys. If you navigate to src/assets/locales, you will find a en.json file, as shown in the image below. You will upload this file to Localazy shortly.

article-image
The English source keys.

⏭️ Next steps 🔗

Test string upload locally 🔗

Before integrating the source key upload into your CI/CD pipeline, it's a good practice to test the upload locally to ensure everything works as expected. Localazy provides a simulation mode using the localazy upload -scommand.

Run the following command in your project root:

localazy upload -s

The -s flag stands for simulate, meaning this command doesn't upload anything to Localazy and will return an error if anything goes wrong.

Now, proceed to set up GitHub Actions for automation.

Automate source key upload with GitHub actions 🔗

To do this, you must first add your Localazy project keys for authentication. Navigate to your repository's Settings → Secrets and variables → Actions and add these repository secrets: LOCALAZY_READ_KEY and LOCALAZY_WRITE_KEY using your Localazy project keys.

article-image

Next, create a new .github/workflows/upload-strings.yml file in your code editor and paste the below content into it:

name: Localazy Upload
	on:
		push:
			branches:
			- dev
        workflow_dispatch:

jobs:
	localazy-upload:
	name: Upload source keys to Localazy
	runs-on: ubuntu-latest

	steps:
		- uses: actions/checkout@v3
		- uses: localazy/upload@v1

	with:
		read_key: ${{ secrets.LOCALAZY_READ_KEY }}
		write_key: ${{ secrets.LOCALAZY_WRITE_KEY }}

This workflow above is triggered by pushing to the dev branch or manually triggering the action. It uses the official Localazy upload action to upload the source keys.

Commit all changes (including the Localazy configuration and workflow files) to the workflow-demo branch, then navigate to GitHub and create a pull request from workflow-demo to dev. After merging the pull request, go to the Actions tab in your repository dashboard. You should see the Localazy Upload workflow trigger. Once it completes successfully, your source strings will be available in Localazy.

article-image
Screenshot showing the successful upload workflow.

Translate source keys on the Localazy dashboard 🔗

After successfully uploading the source keys, you can begin translating. Go to the Translations tab on the Localazy dashboard and add your target languages. This guide uses Spanish, German, Hindi, and Yoruba.

article-image

You have three translation methods to choose from:

  1. Manual translation: Translate all the content yourself manually.
  2. Machine translation: Automatically translate content using machine translation engines like Google Translate, Amazon Translate, or DeepL.
  3. Professional translation: Request translations from professional translators.
📝 Get more information about the professional translation options available in our ultimate guide to Localazy translation services

This guide uses the machine translation option. Once you translate your source language keys, you will see them in the Localazy dashboard.

article-image
The finished translations.

Automate translation download with GitHub actions 🔗

After translating your source keys, the next step is to add a setup for automatically downloading translations when you push to the main branch. You can integrate downloading translations into your build chain by adding the localazy download command to the build script in your package.json file.


{
  "scripts": {
    "prebuild": "localazy download",
    "build": "your-build-command" // e.g webpack --mode=production
  }
}

This way, translations are automatically downloaded when you run npm run build. However, for this demo, you'll push the translated files directly to the main branch.

Create a new .github/workflows/download-translations.ymlfile in your code editor and add the following configuration to it:

name: Localazy Download
on:
  push:
    branches: 
        - main

  workflow_dispatch:

jobs:

  localazy-download:

    name: Download strings from Localazy
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - uses: localazy/download@v1
        with:
          read_key: ${{ secrets.LOCALAZY_READ_KEY }}
          write_key: ${{ secrets.LOCALAZY_WRITE_KEY }}

      - name: Configure Git
        run: |
            git config --local user.email "[email protected]"
            git config --local user.name "GitHub Action."

      - name: Commit and push changes
        run: |
          # Check for changes
          if [[ -n "$(git diff --staged)" ]]; then
            git add src/assets/locales
            git commit -m "Updated translation files from Localazy."
            git push
          else
            echo "No changes in locales"
          fi

This workflow is triggered on push to the main branch and through manual activation. It uses the official Localazy download action to download the translations.

Next, create a pull request from the dev branch to the main branch and merge it. This action will trigger the Localazy Download workflow, as shown in the image below.

article-image
The successful download workflow.

After the workflow executes successfully, the new translation files will be in your src/assets/locales folder. 🎉

Test out the localized application 🔗

Pull the latest changes from the main branch and start the server using npm run serve. You can access the localized versions using these routes:

  • /en for English
  • /es for Spanish
  • /defor German
  • /hi for Hindi
  • /yo for Yoruba

Here's the result in English:

article-image

Spanish:

article-image

German:

article-image

Hindi:

article-image

And Yoruba:

article-image

⚡️ Other CI/CD pipeline integrations 🔗

Localazy CLI supports GitLab CI and Bitbucket Pipelines with similar workflows. Refer to the guides linked above for configurations.

🛠️ Common integration challenges 🔗

You may encounter some challenges when integrating Localazy CLI with your CI/CD pipeline. Here are some common issues and troubleshooting steps:

Authentication issues 🔗

  • ！Error: "Authorization failed! Check your read and write keys."
  • 💡 Solution: Verify your Localazy keys are correctly configured in repository secrets and not swapped.

Upload problems 🔗

  • ！Error: "No files found."
  • 💡 Solution: Make sure the path specified in the upload section of your localazy.json file is correct and has the source key file.

Download issues 🔗

  • ！Error: "Missing translation files."
  • 💡 Solution: Make sure the source language file has been translated to the target language in your Localazy dashboard before downloading. Also, check if the path set in the download section of your localazy.json file is valid.
🏆 Localazy has been recognized as a leading DevOps tool for localization automation. See what other developers are saying about our CI/CD integration capabilities on Tekpon.

➡️ What next? 🔗

As you've seen in this guide, integrating Localazy CLI into CI/CD pipelines greatly improves the localization process. By combining it with GitHub Actions, you've set up an automated system whereby source keys are uploaded on push to the dev branch, and translations are downloaded to the main branch after a pull request is merged. This automation helps reduce the inefficiencies associated with manual localization while keeping translations synchronized with product updates.

You can further improve this workflow by using releases to lock your translation files at specific versions, allowing for safe changes in your Localazy project until the next iteration is finished.

For more resources, check out our documentation or contact us via support. We'll be happy to assist you in crafting your perfect workflow.