Localization can be challenging on its own, and having to regularly remind developers (or yourself) to include the latest localized version before release is not going to end up well at some point. With GitLab’s powerful CI/CD, you only need to configure it properly once. Afterward, you can peacefully take this off your mind. Let's see how.

💡 Integrate your app with Localazy 🔗

Suppose that your mobile, desktop, or web app is ready for localization, and strings in the source language are stored in JSON, YAML, iOS’ strings, Flutter’s ARB, or some other common format.

Sign up to Localazy, create a new app, install the CLI tool, and then create and test your localazy.json configuration. You should be able to upload the source language files and download the localized ones.

The basic configuration could look like this:

{
  "readKey": "read-key",
  "writeKey": "write-key",

  "upload": {
    "type": "json",
    "files": [{
        "pattern": "src/**/locales/${lang}.json",
        "lang": "inherited",
        "path": "${path}"
      }]
  },

  "download": {
    "files": "${path}/${lang}.json"
  }
}

Given that you’ve filled in your readKey and writeKey, you will be already able to manually upload and download strings between your app and Localazy. Let’s move on to automating next.

⚒️ Setup secrets 🔗

Oftentimes it is desirable to hide secrets away from the repository and Localazy keys are no different. We’ll use GitLab’s variables for this. In your GitLab project, go to Settings > CI/CD >Variables and create two variables called LOCALAZY_WRITE_KEY and LOCALAZY_READ_KEY. The result should look like this:

https://directus.localazy.com/_/assets/gitlab-secrets.png

❌ Ignore the localized files 🔗

The source language file  (in my case en.json) is the source of truth, and for localized files, it’s the latest version on Localazy. I don’t need those files to be committed to my repository, as it unnecessarily pollutes the commit history and the translations are already stored once in Localazy.

With the following command placed in the locales folder, we will make sure to upload our source language files and ignore the localized ones:

src/**locales/*.json
!src/**/locales/en.json

🔼 Automate upload 🔗

The GitLab CI/CD is a powerful automation tool with tons of options. If you only need to automate the upload part without any special configuration (such as triggering it only on certain branches or for pull requests), you don’t need to know much about it. However, if you’re aiming to create complex automation rules, you should check out their documentation.

The configuration below is all I need for uploading the source language file en.json to Localazy anytime I merge it to a staging branch. I can run the pipeline anytime there is a change in my source file, and it's done.

All you need to do is to create a .gitlab-ci.yml file with this content:

# This is a base template for Gitlab CI / CD 
# that integrates Localazy upload process into your workflow
# For available upload options https://localazy.com/docs/cli/command-line-options
#
# There are three ways how to authorize the operations (https://localazy.com/docs/cli/authorization)
# - authorization keys in the configuration file (localazy.json)
# - authorization keys in a separate file (localazy.keys.json)
# - authorization keys provided as command-line arguments
#
# If you wish to keep the writeKey and readKey as secrets, we recommend opting for the third option.
# - In Gitlab, define new environment variables (In project: Settings -> CI / CD - > Variables) 
#   called LOCALAZY_WRITE_KEY and LOCALAZY_READ_KEY.
# - Type in your writeKey and readKey respectively

localazy-upload:
    # For additional CLI options, see https://localazy.com/docs/cli/command-line-options
    image:
      name: localazy/cli:latest
    rules:
      - changes:
        - src/**/locale/en.json
      if: '$CI_COMMIT_BRANCH == "staging"'
    script: 
      - localazy upload
        -w $LOCALAZY_WRITE_KEY
        -r $LOCALAZY_READ_KEY

This file will be automatically picked up by GitLab and will trigger a single job called localazy-upload. As you can see, we use the -w $LOCALAZY_WRITE_KEY and -r $LOCALAZY_READ_KEY arguments for authorization. With each push to the repository (regardless of the target branch), the upload operation to Localazy will be triggered.

🔽 Automate download 🔗

When the time comes to build and release a new version of your app, you'll need to have all your translations available. Depending on how your whole build pipeline is set up, there are several ways to get them:

Method 1: Trigger the download command through GitLab 🔗

One of the most common approaches is to use a GitLab job to trigger a single command defined in the repository. This activates a whole sequence of chained scripts that lead to building the full application.

For this, just include the localazy download command at the beginning of the command so that the bundled application includes all the available translations.

Method 2: Create a download pipeline 🔗

Another approach is building a pipeline with several GitLab jobs that may pass workflow artifacts between each other.

If this is your option, define a job to download translations from Localazy and pass the data forward to the following jobs.

Create the file .gitlab-ci.yml for downloading the latest version of localizable files whenever the tag v* is pushed:

localazy-download:
    # For additional CLI options, see https://localazy.com/docs/cli/command-line-options
    image:
      name: localazy/cli:latest
    rules:
      - if: '$CI_COMMIT_TAG =~ /^v.*/'
    script: 
      - localazy download
        -w $LOCALAZY_WRITE_KEY
        -r $LOCALAZY_READ_KEY

As you can see, this job is identical except it triggers the download operation instead of the upload. Of course, this example effectively does nothing as files are only downloaded during the CI/CD pipeline, and if we don’t use them to produce the release build, they are lost once the pipeline is finished and cleared. The exact build configuration strongly depends on your requirements.

✔️ Closing words 🔗

This is only a starter template for GitLab CI/CD. It’s quite likely that you do not wish to fire this automation with each push to each branch, but rather only with accepted pull requests to your staging or production branch. If that is the case, see the documentation about only/except. Nonetheless, this is a perfect basic configuration on which you can build further.

article-image

If you wish to add more triggers to your workflow, check out our Automations feature and guides, or contact us so we can help you refine it based on your needs.