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, Flutter and React Intl / FormatJS. These repositories show both paths: plain local doloc usage for development, and the official doloc-io/doloc-action@v1 GitHub Action for CI/CD automation. 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 --fail-with-body --silent --show-error --compressed 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. For GitHub Actions, use the official doloc-io/doloc-action@v1. In other CI systems, wiring doloc is usually just a curl command plus your CI’s normal commit or artifact step.

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, ARB, Android XML, etc.).
    • Runs doloc with the existing or newly extracted files. In GitHub Actions this is usually the doloc-io/doloc-action@v1 step; elsewhere it is typically a direct curl https://api.doloc.io ... call.
    • Commits/pushes updated translation files when doloc produces changes. (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.
  • Reusable CI Integration: The GitHub Action handles file mappings, update/check mode, and change detection, so your workflow can focus on extraction and committing or proposing the result.

Cons

  • Token Management: You need to store your doloc API token securely in CI (e.g. environment variables/secrets).
  • Commit/PR Permissions: The doloc action itself only needs the checked-out files, but automated commits or pull requests still require the right GitHub token permissions.
  • Commit 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 ensures translation files are still fresh. In GitHub Actions, doloc-io/doloc-action@v1 can run in mode: check; in other CI systems, run curl and fail on a non-empty diff.
    • 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 Commit 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.
    • On GitHub, prefer the doloc GitHub Action and compose it with a commit or pull request action if you want CI to write generated files back. On other CI platforms, call doloc directly with curl.

  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.
    • On GitHub, this maps naturally to local curl/scripts plus doloc-io/doloc-action@v1 in mode: check in CI; elsewhere, use the same local curl command and a diff check.

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.

For repeated local scripts and non-GitHub CI jobs, use a small curl command with flags that fail on HTTP errors while preserving doloc’s helpful error response. See Curl Command Details. If you are using GitHub Actions, the doloc GitHub Action is usually simpler than maintaining the curl command directly in your workflow.

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 GitHub-based CI, use the official doloc-io/doloc-action@v1 for update or check workflows; for other CI systems, a curl step is enough.
  • For step-by-step setup examples, see: