Skip to content

Commit 73cb327

Browse files
andrii-bodnarclaude
andrii-bodnar
and
claude
authored
docs: replace deprecated Context Harvester CLI with AI agents approach (#317)
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent 660d1a1 commit 73cb327

1 file changed

Lines changed: 46 additions & 62 deletions

File tree

‎docs/AI.md‎

Lines changed: 46 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -97,88 +97,72 @@ Context is crucial for accurate and high-quality translations. With the enhanced
9797
> [!IMPORTANT]
9898
> Experiments have shown that LLM + AI Extracted Context can improve the translation quality by up to 75% and LLM + AI Extracted Context + Screenshots + Crowdin AI Tools can improve the translation quality by up to 95%.
9999
100-
### Harvesting Context with Crowdin Context Harvester CLI
100+
### Extracting Context with AI Agents
101101
102102
To ensure that AI translations are accurate and contextually relevant, you need to provide the AI with the necessary context.
103103
104104
Crowdin allows you to provide various levels of context to the AI, including the options available during prompt configuration (glossary terms, TM suggestions, previous and next strings, file context, screenshots, and more). It's highly recommended that you provide the AI with as much context as possible to improve the quality of the translations.
105105
106-
You can use the [Crowdin Context Harvester CLI](https://store.crowdin.com/crowdin-context-harvester-cli) in your CI/CD pipeline to automate the context extraction process. The Context Harvester CLI is designed to simplify the process of extracting context for Crowdin strings from your code. Using Large Language Models (LLMs), it automatically analyzes your project code to find out how each key is used. This information is extremely useful for the human linguists or AI that will be translating your project keys, and is likely to improve the quality of the translation.
106+
The recommended way to extract context from your codebase is to use the [Crowdin CLI context commands](https://crowdin.github.io/crowdin-cli/commands/crowdin-context) together with an AI coding agent (Claude Code, Cursor, GitHub Copilot, etc.). The agent analyzes your codebase to find out how each string is used and stores this information in Crowdin. It is extremely useful for the human linguists or AI that will be translating your project strings and is likely to improve the quality of the translation.
107107
108-
First, install the Crowdin Context Harvester CLI and configure it with your Crowdin project:
108+
The workflow consists of three steps:
109109
110-
```bash
111-
npm i -g crowdin-context-harvester
112-
crowdin-context-harvester configure
113-
```
110+
1. **Download** the strings that are missing context to a local `crowdin-context.jsonl` file:
111+
112+
```bash
113+
crowdin context download --status empty
114+
```
114115

115-
You'll be asked to enter all the necessary information, such as your Crowdin Personal Access Token, Project ID, and other details.
116+
2. **Enrich** — the AI agent fills in the `ai_context` field for each string based on your codebase.
116117

117-
For example:
118+
3. **Upload** the enriched context back to Crowdin:
119+
120+
```bash
121+
crowdin context upload
122+
```
123+
124+
To teach your AI agent this workflow, install the [Crowdin Agent Skills](https://github.com/crowdin/skills). They include the `crowdin-context-cli` skill (context commands and JSONL format) and the `context-extraction` skill (rules for writing meaningful context):
118125

119126
```bash
120-
crowdin-context-harvester configure
121-
? What Crowdin product do you use? Crowdin.com
122-
? Crowdin Personal API token (with Project, AI scopes): __your_personal_token_
123-
? Crowdin project: Test Project
124-
? AI provider: Crowdin AI Provider
125-
? Crowdin AI provider (you should have the OpenAI provider configured in Crowdin): Open AI
126-
? AI model (newest models with largest context window are preferred): gpt-4
127-
? Model context window size in tokens: 128000
128-
? Model maximum output tokens count: 16384
129-
? Check if the code contains the key or the text of the string before sending it to the AI model
130-
(recommended if you have thousands of keys to avoid chunking and improve speed).: I use keys in the code
131-
? Custom prompt file. "-" to read from STDIN (optional):
132-
? Local files (glob pattern): **/*.*
133-
? Ignore local files (glob pattern). Make sure to exclude unnecessary files to avoid unnecessary AI API calls: /**/node_modules/**
134-
? Crowdin files (glob pattern e.g. **/*.*).: **/*.*
135-
? CroQL query (optional):
136-
? Output: Terminal (dry run)
137-
138-
You can now execute the harvest command by running:
139-
140-
crowdin-context-harvester harvest --token="__your_personal_token_" --project=11111 --ai="crowdin" --crowdinAiId=2222 --model="gpt-4" --localFiles="**/*.*" --localIgnore="/**/node_modules/**" --crowdinFiles="**/*.*" --contextWindowSize="128000" --maxOutputTokens="16384" --screen="keys" --output="terminal"
127+
npx skills add crowdin/skills
128+
```
129+
130+
Once the skills are installed, a single prompt is enough for the agent to handle all the steps autonomously:
131+
132+
```
133+
Use the Crowdin CLI to download strings that are missing context, enrich them
134+
with precise UI placement descriptions based on our codebase, and upload the
135+
enriched context back to Crowdin.
141136
```
142137

143-
Once you have configured the Crowdin Context Harvester CLI, you can use the received `harvest` command to extract the context from your project files and provide it to the AI for better translations in your CI/CD pipeline.
138+
At any point, you can check the context coverage of your project by running `crowdin context status`.
144139

145-
Then, add the following steps to your GitHub Actions workflow to extract the context and provide it to the AI:
140+
The context commands can also be executed as part of your GitHub Actions workflow using the `command` input:
146141

147142
```yaml
148-
# Upload sources step
143+
- name: Download strings missing context
144+
uses: crowdin/github-action@v2
145+
with:
146+
command: 'context download'
147+
command_args: '--status empty'
148+
env:
149+
CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
150+
CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
151+
152+
# Enrich the `crowdin-context.jsonl` file with an AI agent
153+
# (e.g., Claude Code GitHub Action)
149154

150-
- uses: actions/setup-node@v7
155+
- name: Upload strings context
156+
uses: crowdin/github-action@v2
151157
with:
152-
node-version: '22'
153-
154-
- name: Extract Context for AI
155-
run: |
156-
npm i -g crowdin-context-harvester
157-
crowdin-context-harvester harvest \
158-
--ai="crowdin" \
159-
--crowdinAiId="${{ secrets.PROVIDER_ID }}" \
160-
--model="gpt-4" \
161-
--localFiles="**/*.*" \
162-
--localIgnore="/**/node_modules/**" \
163-
--crowdinFiles="**/*.*" \
164-
--contextWindowSize="128000" \
165-
--maxOutputTokens="16384" \
166-
--screen="keys" \
167-
--output="terminal"
168-
169-
- name: Upload Context
170-
run: |
171-
crowdin-context-harvester upload \
172-
--token="${{ secrets.CROWDIN_PERSONAL_TOKEN }}" \
173-
--project="${{ secrets.CROWDIN_PROJECT_ID }}" \
174-
--csvFile="crowdin-context.csv"
175-
176-
# Pre-translate with AI step
177-
# Download translations step
158+
command: 'context upload'
159+
env:
160+
CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
161+
CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
178162
```
179163
180-
> [!CAUTION]
181-
> Make sure to omit the personal access token and project ID from the command line and store them in the GitHub Actions secrets. The CLI will automatically use the secrets if they are set.
164+
> [!TIP]
165+
> Read the [Automating i18n Context with AI Agents](https://crowdin.com/blog/automate-i18n-context-with-ai-agents) blog post to learn more about this workflow.
182166
183167
### Automated Screenshots
184168

0 commit comments

Comments
 (0)