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
- Finds keys without a description in your SimpleLocalize project and looks up where your code uses them.
- Asks an AI model to describe each key from the code around it, and saves the descriptions with the places in code
(
references) tosimplelocalize-context.json. - 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"]
}
]
}
| Field | Description |
|---|---|
key | Translation key. |
namespace | Namespace of the key, omitted when the key has none. |
context | The description, up to 500 characters. Edit it freely; an empty context is skipped on upload. |
references | Where 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
| Option | Description |
|---|---|
--api-key | Project API key. Default: SIMPLELOCALIZE_API_KEY |
--context | Context file (-c). Default: simplelocalize-context.json |
--dry-run | Preview changes without writing or uploading anything |
harvest
| Option | Description |
|---|---|
--search-dir | Directory with your source code. Default: . |
--exclude | Glob to skip, repeatable, e.g. --exclude "**/*.test.ts" |
--namespace | Only keys from this namespace. Default: all |
--limit | Max keys per run. Default: 200 |
--model | AI model. Default: claude-opus-5-5 or gpt-5.4 |
--overwrite | Describe keys already in the context file again |
upload
| Option | Description |
|---|---|
--overwrite | Replace code descriptions that keys already have |
--no-references | Don'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
.gitignoreis read, without negations.
Source code
Context Harvester is open source under the MIT license: simplelocalize/context-harvester.