❓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.
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.
👶 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
- manually merge new translations from
- 🛠️ 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.
🏆 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.