Automated Localization: Bitbucket Pipelines ❤ Localazy

❓Why automate localization with CI/CD? 🔗

Localization can be challenging on its own and having to regularly download the latest localization files can be tedious and error-prone.

When using Bitbucket Pipelines, you'll only need to integrate Localazy once. Afterward, you can peacefully take this off your mind.

📌 Requirements 🔗

Setup Localazy CLI 🔗

To automate uploading source keys and downloading translations, you need to install Localazy CLI and create a configuration file in your project root.

To authorize Localazy CLI for uploading and downloading, you have to provide the writeKey and readKey of your Localazy project.

Select the project from your Dashboard, go to Project settings > Access keys, and copy the writeKey and readKey to your localazy.json configuration file.

Localazy Access Keys

If you cannot store project keys in the repository, you can delete writeKey and readKey from localazy.json and provide them as CLI arguments.

Commit localazy.json to your repository.

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

Localazy CLI resources 🔗

Documentation
Authorization
Npm package @localazy/cli
Docker image localazy/cli
or a native app for all major platforms

Setup Bitbucket pipeline variables 🔗

You only need this step if you do not have writeKey and readKey stored in the localazy.json configuration file.

In your Bitbucket repository, go to Repository Settings > Pipelines > Repository variables and add LOCALAZY_WRITE_KEY and LOCALAZY_READ_KEY variables.

Bitbucket Pipeline Variables

👶 Sample development workflow 🔗

To demonstrate the configuration of Bitbucket Pipelines, we will use a sample development workflow, which consists of the following steps:

✨ features are created in feature branches and merged into the develop branch
🛠️ CI/CD: push to the develop branch
- build and deploy to the development server
🚀 CI/CD: push to the main branch
- build and deploy to the production server

It is likely that your team uses a more complex development workflow, or you have a different branching model, but the demonstrated principles are universal, and it is easy to integrate them into any development workflow.

📤 How to upload source keys? 🔗

You should upload your source keys after pushing changes into the first common branch:

✨ features are created in feature branches and merged into the develop branch
🛠️ CI/CD: push to the develop branch
- automatically upload source keys to Localazy
- build and deploy to the development server
🚀 CI/CD: push to the main branch
- build and deploy to the production server

Add the following step to your bitbucket-pipelines.yml and adjust it according to your development workflow. The step is triggered when a commit containing changes in source keys is pushed to the develop branch.

image: atlassian/default-image:4

pipelines:
  branches:
    develop:
      - step:
          name: Upload source keys to Localazy
          condition:
            changesets:
              includePaths:
                # Update the path according to your project structure
                - 'locales/en.json'
          script:
            - npm install @localazy/cli -g
            # Remove -w -r arguments if your keys are stored in the repository
            - localazy upload -w $LOCALAZY_WRITE_KEY -r $LOCALAZY_READ_KEY

Uploading from feature branches 🔗

If your development workflow requires uploading translations from feature branches, you must configure branching in Localazy CLI. This is an advanced feature, and each team integrates it into their development workflow in a different way. We recommend that you finish this guide and then read about the branching options of the Localazy CLI.

If you are not sure how to properly configure branching in Localazy CLI, you can contact our support or book a consultation with one of our software engineers.

😏 Should I store translations in the repository? 🔗

The decision whether to store translations in the repository depends on the needs of your technology stack. In most cases, it is more advantageous to ignore files with translations in .gitignore and download them before building the application using Localazy CLI.

Download translations before build 🔗

In the following development workflow, your developers have the latest translations continuously available during the application development without the need to merge them manually, and your translators have time to translate before the application is released.

✨ Features are created in feature branches and merged into the develop branch
- automatically download translations from Localazy
🛠️ CI/CD: push to the develop branch
- automatically upload source keys to Localazy
- automatically download translations from Localazy
- build and deploy to the development server
🚀 CI/CD: push to the main branch
- automatically download translations from Localazy
- build and deploy to the production server

Before your build command, call localazy download and download all translations using Localazy CLI. This solution is universal for all languages and frameworks.

📥 How to download and update translations? 🔗

If you need to have translations stored in the repository, you must update them regularly. Translations can be updated by a semi-automatic CI trigger or automatically once they are published with Localazy Webhooks.

Download translations after the CI trigger 🔗

In the following workflow, translations are automatically downloaded and committed to the repository after each push to the develop branch. Your developers must merge new translations into existing feature branches, and your translators must inform you when the translation is complete so you can merge the translations into the develop branch.

✨ features are created in feature branches and merged into the develop branch
- manually merge new translations from develop
🛠️ CI/CD: push to the develop branch
- automatically upload source keys to Localazy
- automatically download translations from Localazy
- commit translations if files changed
- build and deploy to the development server
🚀 CI/CD: push to the main branch
- build and deploy to the production server

Add the following step to your bitbucket-pipelines.yml and adjust it according to your development workflow.

image: atlassian/default-image:4

pipelines:
  branches:
    develop:
      - step:
          name: Download translations from Localazy and commit changes
          script:
            - npm install @localazy/cli -g
            # Remove -r argument if your key is stored in the repository
            - localazy download -r $LOCALAZY_READ_KEY
            - git add .
            - git commit -m "[skip ci] New translations from Localazy" || true
            - git push

Download translations after they are published 🔗

All changes in translations are automatically published within five minutes of the last change made. Using a webhook, you can propagate this event to your CI/CD. If we use the workflow from the previous step, the pipeline for the develop branch would automatically start after the translations are published.

You need to create a publicly accessible endpoint that will serve as an intermediary between the Localazy webhook and Bitbucket Pipelines.

The Localazy webhook will send a POST request to the endpoint, and the endpoint will start the pipeline for the branch via the Bitbucket API. An example of endpoint implementation is available in the sample repository.

🍰 Sample repository 🔗

The accompanying repository is available on GitHub. It contains a sample development workflow from this article and an example webhook endpoint.

Bitbucket pipelines

🏆 Conclusion 🔗

By now, you should have an idea of what the options are for integrating automatic localization into your development workflow. The examples given are only demonstrative, and it is very likely that you will adapt them according to the needs of your team, but they serve as a good foundation on which to build.