A Bundled Localization Approach: Integrating Translations into Your CI/CD Pipeline

Note: This approach is designed for customers who prefer to bundle and version their translation files as part of the build process—instead of using a fully “connected” locize approach (where translations are dynamically fetched from our CDN and can be updated without a redeploy). For a truly continuous localization experience, we recommend connecting your code directly with the locize CDN (see Modern Continuous Localization and Using the locize CDN). However, if you have requirements such as hosting translations locally or concerns over confidential translation texts (see Confidentiality Considerations), this CI/CD integration approach is a very valid alternative.

In today’s global market, software teams must deliver applications that speak the language of every user—even as new features roll out continuously. Traditional localization methods, which treat translation as a post-development add-on, can slow down release cycles and create friction between development and translation teams. By integrating localization into your CI/CD pipeline, you can treat translation files like any other piece of code—automating the extraction, review, and deployment of localized content.

‍

The Evolution from Manual to Automated Localization

Historically, localization was handled in distinct phases: developers would freeze strings at the end of a sprint, export them, send them for translation, and then re-import the updates. This “localization freeze” led to delays and misaligned versions between code and translations. Today’s agile teams are embracing “localization as code,” where translation workflows become an integral, automated part of the development process.

Key Insight: When translation is integrated with your CI/CD pipeline, you can update or add translations as part of your regular build—ensuring that updates across multiple languages align with every new code commit.

Integrating Localization into Your CI/CD Pipeline

1. Instrument Your Code for Internationalization

Begin by ensuring that your application is internationalized. For a connected locize approach (where you fetch translations on the fly from our CDN), you might use the i18next-locize-backend—which enables dynamic updates and the “save missing” feature via our API.

If you prefer to bundle translations with your app (hosting them locally), you can use alternatives such as i18next-http-backend or i18next-resources-to-backend to load resource files directly from your local assets. For example, using i18next-http-backend:

import i18next from 'i18next';
import HttpBackend from 'i18next-http-backend';

i18next.use(HttpBackend).init({
  fallbackLng: 'en',
  debug: false,
  backend: {
    loadPath: '/locales/{{lng}}.json'
  }
});

Note: The “save missing” feature (which automatically pushes new strings to locize) is available only with i18next-locize-backend or when you directly consume our API (Missing Translations API).

2. Automate String Extraction & Synchronization

Modern TMS tools like locize support automatic detection of missing strings. In development, you can use i18next-locize-backend together with the “save missing” feature so that any new keys are automatically pushed to your translation dashboard. For production, you might opt to disable this dynamic feature and instead use i18next-http-backend (or another resource-loading backend) to load pre-downloaded, bundled translation files.

Below is a code example that differentiates backend configuration by environment:

import i18next from 'i18next';
import LocizeBackend from 'i18next-locize-backend';
import HttpBackend from 'i18next-http-backend';

const isDevelopment = process.env.NODE_ENV === 'development';

i18next
  .use(isDevelopment ? LocizeBackend : HttpBackend)
  .init({
    fallbackLng: 'en',
    debug: isDevelopment,
    backend: {
      loadPath: isDevelopment
        ? 'https://api.locize.com/{{projectId}}/{{version}}/{{lng}}/{{ns}}'
        : '/locales/{{lng}}.json'
    },
    saveMissing: isDevelopment
  });

Explanation:

• Development: Uses the locize backend with “save missing” enabled to dynamically push new keys.
• Production: Uses the HTTP backend to load bundled translation files from a local path.

3. Integrate Upload, Sync, and Download Operations into CI/CD

Embedding localization commands directly into your CI/CD workflow ensures that your app always packages the latest translation files. Depending on your preferred tooling, you have multiple options:

• GitHub Actions:
  Use our official GitHub Action for downloading translations (see locize GitHub Action documentation). For example:

jobs:
  my_job:
    runs-on: ubuntu-latest
    name: download and push
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Download translations
        uses: locize/download@v1
        with:
          project-id: ${{ secrets.LOCIZE_PROJECT_ID }}
      - name: Commit & Push changes
        uses: actions-js/push@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

• CLI Sync Command:
  Alternatively, use the locize CLI to synchronize translation files:

locize sync --api-key $LOCALIZE_API_KEY --project-id $LOCALIZE_PROJECT_ID

• This command downloads and synchronizes translations from locize with your local repository. (See the locize CLI documentation for details.)

Best Practices for Implementation

To ensure a smooth integration of localization into your CI/CD pipeline, consider the following best practices:

• Use Environment Variables:
  Keep sensitive API keys secure by leveraging your CI/CD system’s secret management features.
• Automate Localization Testing:
  Integrate scripts into your pipeline that validate translation file formats and catch missing or inconsistent keys.
• Leverage Built-In Versioning:
  Locize natively manages multiple versions of your translations (Versioning Documentation). Use this feature to maintain separate translation branches (e.g., “development” vs. “production”) for more controlled deployments.
• Set Up Notifications:
  Configure locize’s notification options (Notifications Documentation) so that your team stays up to date. This allows rapid iteration and quality control.
• Define Automated Workflows:
  Use your CI/CD platform to trigger localization tasks only when needed (e.g., on pull requests to staging or production branches) to optimize resource usage and maintain stability.

Conclusion

Localization is no longer an afterthought—it’s an integral part of modern software development. By treating translation workflows as code and embedding them into your CI/CD pipeline, you can achieve faster time-to-market, higher quality, and a seamless user experience for a global audience.

While connecting your code directly with the locize CDN is our recommended “connected” approach for real continuous localization, this CI/CD bundling strategy is ideal for customers who prefer to host translation files within their repository. This approach also addresses concerns like maintaining confidentiality of translation texts.

Whether you’re a developer, tech lead, or head of software engineering, integrating localization into your development process is a strategic move that keeps you competitive in a multilingual world.