Login Account
Table of contents

When to Run doloc?

One of the most common questions is when to actually execute doloc in your workflow. Should a developer run it locally every time new texts appear? Should it run automatically in the CI/CD pipeline and commit updated translation files?

Below, we share typical scenarios and discuss the pros and cons for each approach, based on our experience and customer feedback. We’ll also include some best practices that can help ensure translations are never forgotten and that changes remain nicely self-contained.

Examples

We also have set up example/demo repositories for Android and React Intl / FormatJS. These repositories show how to integrate doloc and how to run it locally or in a CI/CD pipeline. Please check them out for a hands-on experience!

1. Developer-Run Approach

Typical usage: Developers run doloc on their machine after adding or updating any source texts (or whenever they feel a refresh is needed).

Workflow

  1. Developer updates source code with new or changed texts.
  2. Developer runs the extraction script (e.g. ng-extract-i18n-merge, formatjs extract, etc.). Depending on the framework, this step may not be needed. If this step is needed, it is recommended to combine this with the doloc command.
  3. Developer runs doloc locally (possibly using a script or alias) to update the translation files: 
    curl https://api.doloc.io -H "Authorization: Bearer $API_TOKEN" ...
  4. Developer commits the updated translation files to the repository (often in the same commit as the source text changes).

Pros

  • Self-Contained Changes: Original changes and updated translations can all live in a single commit. This keeps everything neatly packaged and easier to review.
  • Immediate Feedback: Developers see translations as soon as they update the source texts.
  • Simplicity: No extra CI/CD steps or secrets management required.
  • Combined Extraction + Translation Step: Especially in npm-based setups, you can wrap extraction and the doloc command into a single script (e.g., "update-i18n": "ng extract-i18n && curl ...") so you can’t “forget” to update translations.

Cons

  • Requires Local Action: Each developer must run the command; if they skip it, the translations lag behind—though combining extraction and doloc in a single script helps mitigate this.
  • Token Handling: Must store or configure an API token locally (though, for private repos, storing the token in .env or even committing it is often acceptable since the main risk is unauthorized usage of your quota).

Note: There is typically no real risk of machine inconsistencies here. Modern tooling (npm, curl, etc.) and doloc itself work consistently across platforms.

2. CI/CD Pipeline Approach

Typical usage: The CI/CD pipeline automatically runs doloc whenever a new commit is pushed (or at a specific stage in the pipeline) and then commits the updated translation files back to the repository.

Workflow

  1. A developer changes texts and commits those changes.
  2. The CI pipeline detects changes in the source files.
  3. The pipeline:
    • Extracts or updates translation files (XLIFF/JSON).
    • Runs doloc with the existing or newly extracted files.
    • Commits/pushes the updated translation files. (Optionally, it might skip this and subsequent steps if no translations are needed.)
  4. Optionally, it may open a pull request or automatically merge them, depending on your Git setup.

Pros

  • Full Automation: Eliminates the risk of forgetting to translate; the pipeline does the job reliably.
  • Consistent Process: Everyone gets the same updated files, committed by the pipeline.

Cons

  • Token Management: You need to store your doloc API token securely in CI (e.g. environment variables/secrets).
  • Increased Complexity: Setting up your CI pipeline to commit back changes can be tricky (requiring Git user credentials or special permissions).
  • Merge Noise: If the pipeline commits changes automatically, you may end up with many small commits for each translation update.

3. Hybrid (Developer + CI Check)

Typical usage: Developers run doloc locally, but there is an additional check in CI to verify translations are up to date.

Workflow

  1. Developer changes or adds new texts.
  2. Developer runs doloc locally and commits the updated files. (analogous to the Developer-Run Approach)
  3. On CI, a verification step (e.g. npm run extract + diff check) ensures no untranslated strings remain.
    • Optionally: If any strings are missing translations, the build fails or a separate PR is opened.

Pros

  • Fails Fast: If a developer forgets to run doloc, the pipeline immediately flags untranslated texts.
  • Less Merge Noise: The pipeline won’t keep committing changes automatically, but it will catch issues.
  • Full Coverage: You get the convenience of local translations plus a safety net in CI.

Cons

  • Extra Setup: You must configure your pipeline to do a “translation check” step.
  • Local Token Still Needed: Developers still require local tokens and instructions.

General Recommendations

  1. Local developer approach is often the simplest for small to medium-sized teams or individuals:

    • Combine extraction and translation in a single command ("update-i18n": "npm run extract && npm run doloc-fr && ...").
    • Commit both source changes and updated translation files together for a self-contained workflow.

  2. CI/CD pipeline approach can be appealing for larger teams:

    • Ensures absolutely everyone gets updated translations automatically.
    • More complex to set up (token management, automated commits).

  3. Hybrid is ideal if:

    • You want local control plus CI checks to ensure consistency.
    • You don’t want automated commit merges from the pipeline but still want to guarantee no one forgets translations.

Important: In all approaches, handle your API token securely. For private repos, committing the token or storing it in an .env is common. For open-source/public repos, environment variables in your CI or local .env files are safer.

Bottom Line

  • Run doloc whenever your source texts change, so translations stay fresh.
  • Decide between developer-local, CI/CD, or hybrid based on team size, workflow preferences, and security requirements.
  • Consider combining extraction and doloc commands in a single script so it’s never forgotten, and commit changes (source + translations) together where possible.
  • For step-by-step setup examples, see: