Extensions

Context Harvester

Context Harvester is an open-source command-line tool that writes descriptions for your translation keys. It finds where each key without a description is used in your code, asks an AI model what the text is (a button, a title, an error message, which screen it is on, what {amount} means), and saves the result to a file in your repository. You review the file and upload it to SimpleLocalize.

Translators see the description next to the key, and auto-translation uses it as context, so short and ambiguous texts like "Charge" or "Save" get translated correctly.

npx @simplelocalize/context-harvester          # describe keys, save to simplelocalize-context.json
npx @simplelocalize/context-harvester upload   # upload the reviewed file

Get started

You need the project API key from Settings > Credentials and an API key from Anthropic or OpenAI.

Run it in the root of your repository:

export SIMPLELOCALIZE_API_KEY=<project API key>
export ANTHROPIC_API_KEY=<your Anthropic key>     # or OPENAI_API_KEY

npx @simplelocalize/context-harvester --dry-run   # preview, writes nothing
npx @simplelocalize/context-harvester             # writes simplelocalize-context.json
# review the file, then:
npx @simplelocalize/context-harvester upload

If your repository has a simplelocalize.yml with apiKey (the CLI configuration file), the API key is read from it automatically.

How it works

  1. Finds keys without a description in your SimpleLocalize project and looks up where your code uses them.
  2. Asks an AI model to describe each key from the code around it, and saves the descriptions with the places in code (references) to simplelocalize-context.json.
  3. You review the file, for example in a pull request, and run upload.

Your edits in the file are kept when you run it again. upload only updates existing keys and doesn't replace descriptions they already have.

Context file

{
  "version": 1,
  "keys": [
    {
      "key": "checkout.pay",
      "namespace": "web",
      "context": "Primary button on the last checkout step that charges the saved card. {amount} is the order total with currency.",
      "references": ["src/checkout/PaymentStep.tsx:42"]
    }
  ]
}
FieldDescription
keyTranslation key.
namespaceNamespace of the key, omitted when the key has none.
contextThe description, up to 500 characters. Edit it freely; an empty context is skipped on upload.
referencesWhere the key is used in your code, as path:line. Refreshed on every run.

The file is sorted by namespace and key, so diffs stay small. Commit it to your repository.

Where descriptions go

upload saves the descriptions as code descriptions. Translators see them in the Translation Editor and AI auto-translation uses them, but they are read-only there, because the file in your repository is their source of truth: to change one, edit the file and upload it again. Translator descriptions are never changed. Read more about the difference in Descriptions.

Keys that already have a description, written by a translator or imported from your translation files, are not described again and are not overwritten on upload unless you pass --overwrite.

upload also saves the references of each key in SimpleLocalize. Up to about 10 paths are stored per key, together with the number of all places. Run upload with --no-references to keep them in your repository only.

Options

Common options

OptionDescription
--api-keyProject API key. Default: SIMPLELOCALIZE_API_KEY
--contextContext file (-c). Default: simplelocalize-context.json
--dry-runPreview changes without writing or uploading anything

harvest

OptionDescription
--search-dirDirectory with your source code. Default: .
--excludeGlob to skip, repeatable, e.g. --exclude "**/*.test.ts"
--namespaceOnly keys from this namespace. Default: all
--limitMax keys per run. Default: 200
--modelAI model. Default: claude-opus-5-5 or gpt-5.4
--overwriteDescribe keys already in the context file again

upload

OptionDescription
--overwriteReplace code descriptions that keys already have
--no-referencesDon't upload the references

AI providers and privacy

Set ANTHROPIC_API_KEY (uses claude-opus-5-5) or OPENAI_API_KEY (uses gpt-5.4). The provider is called directly with your key and receives only the key, its source text and a few lines of code around its usages. Your code is not sent to SimpleLocalize, only the descriptions and references. Use --exclude for paths that must not leave your machine.

Running in GitHub Actions

Generated descriptions should be reviewed before they reach translators. Run the harvest on a schedule and open a pull request with the changes, then upload the file once the pull request is merged:

# .github/workflows/translation-context.yml
name: Translation context
on:
  schedule:
    - cron: "0 6 * * 1"
  push:
    branches: [main]
    paths: [simplelocalize-context.json]

jobs:
  harvest:
    if: github.event_name == 'schedule'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - run: npx @simplelocalize/context-harvester
        env:
          SIMPLELOCALIZE_API_KEY: ${{ secrets.SIMPLELOCALIZE_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - uses: peter-evans/create-pull-request@v7
        with:
          title: "Translation context for new keys"
          branch: translation-context
  upload:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @simplelocalize/context-harvester upload
        env:
          SIMPLELOCALIZE_API_KEY: ${{ secrets.SIMPLELOCALIZE_API_KEY }}

Limitations

  • Keys built at runtime (t(`errors.${code}`)) or stored in variables can't be found; they are listed as "not found in code".
  • A quoted key followed by : or = is treated as a definition (JSON, YAML, .strings), not a usage.
  • Only the root .gitignore is read, without negations.

Source code

Context Harvester is open source under the MIT license: simplelocalize/context-harvester.

Last updated: November 16, 2026Author: Jakub Pomykała