Docs and quickstart

Quickstart

1. Run the check

In the root of your project:

Without a config file, the gate looks for the usual layouts of Laravel, next-intl, i18next, vue-i18n, Rails, Flutter, Xcode, Android, .NET, gettext and XLIFF, and checks every locale it finds against the source. Nothing is sent anywhere.

2. Save the layout

This writes what the gate detected to shipglot.config.json. Commit it, and adjust the source locale, file patterns and check levels there.

3. Add the GitHub Action

Add .github/workflows/translations.yml:

name: Translations
on: pull_request
jobs:
  shipglot:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
      - uses: aurelien64/shipglot@v0
        with:
          fail-on: error

Pull requests then get annotations on the lines that break and a job summary. The guides have a workflow for each framework with the right paths filter.

GitHub Action inputs

From action.yml of aurelien64/shipglot@v0. The step's exit-code output is 0 when clean and 1 when findings reached fail-on.

To show findings in GitHub code scanning, set sarif-file and upload it with github/codeql-action/upload-sarif. Other CI systems can run npx shipglot check --reporter sarif=shipglot.sarif or --reporter json directly.

Config

{
  "sourceLocale": "en",
  "files": [
    { "format": "next-intl-json", "path": "messages/{locale}.json" },
    { "format": "android-xml", "path": "app/src/main/res/values{-locale}/strings.xml" }
  ],
  "glossary": "glossary.json",
  "identical": ["OK", "Email"],
  "maxLength": { "nav.*": 24 },
  "checks": { "length-ratio": "off", "untranslated": "error" }
}

Path patterns: {locale}, {namespace}, {-locale} and {.locale} (empty for the source file), * and **/. Every check can be set to error, warning, info or off. The 13 format ids are listed by npx shipglot formats.

A glossary file lists approved terms per locale and words never to translate:

{
  "terms": [{ "source": "matter", "translations": { "fr": "dossier", "es": "asunto" } }],
  "doNotTranslate": ["Shipglot", "GitHub"]
}

Lockfile and changed keys

npx shipglot lock writes shipglot.lock with a SHA-256 hash of every source string and translation. Commit it. After that, check reports translations whose source changed since they were locked (stale-translation), check --changed checks only keys changed since the lockfile, which keeps pull request runs fast, and status lists missing, stale and new translations per locale.

Commands

Common options: --locale fr,de, --config <file>, --root <dir>, --fail-on error|warning|never, --changed, --verbose. npx shipglot --help lists all of them.

Output and exit codes

Reporters: text (default), json, sarif and github (pull request annotations and a job summary). Add =file to write a report to a file, and repeat the flag for several: --reporter github --reporter sarif=shipglot.sarif.

• 0: no findings at or above --fail-on
• 1: findings reached --fail-on (default error)
• 2: usage or config error, for example no files for the source locale

Hosted translation

Hosted translation is not open yet. This is how it will work; the commands exist in the CLI today and need a token.

npx shipglot translate --dry-run       # what would be sent; nothing leaves the machine
export SHIPGLOT_TOKEN=...              # from your Shipglot account
npx shipglot translate                 # translate missing, new and stale keys, then check them
npx shipglot push                      # send the files to the reviewer editor

translate sends only the keys that need a translation, with context from your code, writes the results with the format's own writer, runs the gate on them and updates shipglot.lock. A string that fails the checks is reported and not written. The security page lists what is sent. Free up to 500 source keys; see pricing.

Guides, checks and tools

• Framework guides11 guides with a config, a workflow and real findings for each framework.
• ChecksAll 17 checks, each with a failing and a passing example.
• Browser tools6 checkers that run in the page. Nothing is uploaded.
• FAQThe gate, hosted translation, pricing and security.