my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	# 🌍 18 Languages - Automated i18n Translation Workflow
#2
#3	> Comprehensive guide to the automated internationalization (i18n) workflow that translates your AI agents into 18 languages using OpenAI GPT models.
#4
#5	---
#6
#7	## 📋 Table of Contents
#8
#9	- [Overview](#overview)
#10	- [Supported Languages](#supported-languages)
#11	- [Prerequisites](#prerequisites)
#12	- [How It Works](#how-it-works)
#13	- [Step-by-Step Workflow](#step-by-step-workflow)
#14	- [File Structure](#file-structure)
#15	- [Configuration](#configuration)
#16	- [Running the Workflow](#running-the-workflow)
#17	- [Understanding the Process](#understanding-the-process)
#18	- [Translation Features](#translation-features)
#19	- [Validation & Quality Control](#validation--quality-control)
#20	- [GitHub Actions Integration](#github-actions-integration)
#21	- [Troubleshooting](#troubleshooting)
#22	- [Advanced Topics](#advanced-topics)
#23
#24	---
#25
#26	## Overview
#27
#28	This project includes an automated translation workflow that takes your AI agent definitions from the `/src` directory and automatically:
#29
#30	1. ✅ Formats and validates the agent JSON files
#31	2. ✅ Generates missing content (categories, examples, opening messages)
#32	3. ✅ Translates all text fields to 18 languages using OpenAI GPT
#33	4. ✅ Creates organized translation files in `/locales`
#34	5. ✅ Validates translation quality and language accuracy
#35	6. ✅ Builds a CDN-ready public distribution
#36
#37	Key Benefit: Submit your agent in English once, and it becomes available in 18 languages automatically.
#38
#39	---
#40
#41	## Supported Languages
#42
#43	The workflow supports 18 languages based on BCP 47 standards:
#44
#45	\| Code \| Language \| Region \|
#46	\| ------- \| --------------------- \| ------------- \|
#47	\| `en-US` \| English \| United States \|
#48	\| `ar` \| Arabic \| \|
#49	\| `bg-BG` \| Bulgarian \| Bulgaria \|
#50	\| `zh-CN` \| Chinese (Simplified) \| China \|
#51	\| `zh-TW` \| Chinese (Traditional) \| Taiwan \|
#52	\| `de-DE` \| German \| Germany \|
#53	\| `es-ES` \| Spanish \| Spain \|
#54	\| `fa-IR` \| Persian (Farsi) \| Iran \|
#55	\| `fr-FR` \| French \| France \|
#56	\| `it-IT` \| Italian \| Italy \|
#57	\| `ja-JP` \| Japanese \| Japan \|
#58	\| `ko-KR` \| Korean \| South Korea \|
#59	\| `nl-NL` \| Dutch \| Netherlands \|
#60	\| `pl-PL` \| Polish \| Poland \|
#61	\| `pt-BR` \| Portuguese \| Brazil \|
#62	\| `ru-RU` \| Russian \| Russia \|
#63	\| `tr-TR` \| Turkish \| Turkey \|
#64	\| `vi-VN` \| Vietnamese \| Vietnam \|
#65
#66	---
#67
#68	## Prerequisites
#69
#70	### Required Environment Variables
#71
#72	You MUST have an OpenAI API key configured before running the translation workflow:
#73
#74	#### For Local Development
#75
#76	Create a `.env` file in the project root:
#77
#78	```bash
#79	# .env
#80	OPENAI_API_KEY=sk-your-api-key-here
#81	OPENAI_PROXY_URL=https://api.openai.com/v1 # Optional: custom endpoint
#82	```
#83
#84	#### For GitHub Actions
#85
#86	Add these secrets to your GitHub repository:
#87
#88	1. Go to Settings → Secrets and variables → Actions
#89	2. Add the following secrets:
#90	- `OPENAI_API_KEY`: Your OpenAI API key
#91	- `OPENAI_PROXY_URL`: (Optional) Custom OpenAI endpoint
#92	- `GH_TOKEN`: GitHub token for automated commits
#93
#94	### Required Tools
#95
#96	- Node.js 18+ or Bun runtime
#97	- Git for version control
#98	- OpenAI API account with credits
#99
#100	---
#101
#102	## How It Works
#103
#104	The i18n workflow follows this high-level process:
#105
#106	```
#107	┌─────────────────┐
#108	│ /src/*.json │ ← Your agent files (English)
#109	│ (41 agents) │
#110	└────────┬────────┘
#111	│
#112	▼
#113	bun run format ← Formats & translates
#114	│
#115	├─ Validates JSON structure
#116	├─ Generates missing content
#117	├─ Extracts translatable fields
#118	├─ Calls OpenAI GPT for translation
#119	└─ Creates locale files
#120	│
#121	▼
#122	┌─────────────────┐
#123	│ /locales/ │ ← Translation output
#124	│ agent-name/ │
#125	│ ├─ index.json │ (en-US default)
#126	│ ├─ index.ar.json
#127	│ ├─ index.zh-CN.json
#128	│ └─ ... 18 files
#129	└────────┬────────┘
#130	│
#131	▼
#132	bun run build ← Builds distribution
#133	│
#134	▼
#135	┌─────────────────┐
#136	│ /public/ │ ← CDN-ready output (generated, gitignored)
#137	│ index.json │
#138	│ agents/ │
#139	└─────────────────┘
#140	```
#141
#142	> \[!NOTE]: The `/public` directory is in `.gitignore` and only created when you run `bun run build`. It's not committed to Git and not required for the translation workflow.
#143
#144	---
#145
#146	## Step-by-Step Workflow
#147
#148	### Step 1: Create Your Agent
#149
#150	Create a new agent file in `/src`:
#151
#152	```bash
#153	/src/your-agent-name.json
#154	```
#155
#156	Example agent structure:
#157
#158	```json
#159	{
#160	"author": "your-github-username",
#161	"config": {
#162	"systemRole": "You are an expert DeFi analyst specializing in yield optimization..."
#163	},
#164	"identifier": "your-agent-name",
#165	"meta": {
#166	"title": "Your Agent Title",
#167	"description": "Brief description of what your agent does",
#168	"avatar": "🤖",
#169	"tags": ["defi", "yield", "optimization"]
#170	},
#171	"schemaVersion": 1
#172	}
#173	```
#174
#175	### Step 2: Format and Translate
#176
#177	Run the format command:
#178
#179	```bash
#180	bun run format
#181	```
#182
#183	This command will:
#184
#185	- ✅ Validate your JSON structure
#186	- ✅ Generate missing fields (category, examples, opening messages)
#187	- ✅ Extract all translatable content
#188	- ✅ Call OpenAI to translate to 18 languages
#189	- ✅ Create organized folders in `/locales`
#190
#191	Expected Output:
#192
#193	```
#194	/locales/
#195	your-agent-name/
#196	├── index.json (en-US)
#197	├── index.ar.json (Arabic)
#198	├── index.bg-BG.json (Bulgarian)
#199	├── index.de-DE.json (German)
#200	├── index.es-ES.json (Spanish)
#201	├── index.fa-IR.json (Persian)
#202	├── index.fr-FR.json (French)
#203	├── index.it-IT.json (Italian)
#204	├── index.ja-JP.json (Japanese)
#205	├── index.ko-KR.json (Korean)
#206	├── index.nl-NL.json (Dutch)
#207	├── index.pl-PL.json (Polish)
#208	├── index.pt-BR.json (Portuguese)
#209	├── index.ru-RU.json (Russian)
#210	├── index.tr-TR.json (Turkish)
#211	├── index.vi-VN.json (Vietnamese)
#212	├── index.zh-CN.json (Simplified Chinese)
#213	└── index.zh-TW.json (Traditional Chinese)
#214	```
#215
#216	### Step 3: Validate Translations (Optional)
#217
#218	Validate the quality of translations:
#219
#220	```bash
#221	# Validate all translation files
#222	bun run i18n:validate
#223
#224	# Validate and fix issues
#225	bun run i18n:fix
#226
#227	# Validate and delete invalid files
#228	bun run i18n:clean
#229	```
#230
#231	### Step 4: Build for Distribution (Optional)
#232
#233	Build the final public distribution:
#234
#235	```bash
#236	bun run build
#237	```
#238
#239	This creates CDN-ready files in `/public` (gitignored):
#240
#241	- Agent index files
#242	- Individual agent JSON files
#243	- Schema definitions
#244	- All language variants
#245
#246	> \[!NOTE]: This step is optional during development. The `/public` directory is automatically generated during deployment (e.g., by GitHub Actions). You typically only need to run `bun run format` locally.
#247
#248	---
#249
#250	## File Structure
#251
#252	### Source Directory (`/src`)
#253
#254	```
#255	/src/
#256	├── airdrop-hunter.json
#257	├── alpha-leak-detector.json
#258	├── defi-yield-farmer.json
#259	└── ... (41 agents total)
#260	```
#261
#262	Each agent is a single JSON file in English (en-US).
#263
#264	### Locales Directory (`/locales`)
#265
#266	After running `bun run format`:
#267
#268	```
#269	/locales/
#270	├── airdrop-hunter/
#271	│ ├── index.json (en-US)
#272	│ ├── index.ar.json
#273	│ ├── index.zh-CN.json
#274	│ └── ... (18 language files)
#275	│
#276	├── alpha-leak-detector/
#277	│ ├── index.json
#278	│ └── ... (18 language files)
#279	│
#280	└── ... (41 agent folders)
#281	```
#282
#283	Each agent gets its own folder with 18 translation files.
#284
#285	### Public Directory (`/public`)
#286
#287	Generated by `bun run build` - Not in Git
#288
#289	The `/public` directory is:
#290
#291	- ✅ Generated by the build command
#292	- ✅ Gitignored (listed in `.gitignore`)
#293	- ✅ Optional for development - only needed for deployment
#294	- ✅ CDN-ready output for serving agents
#295
#296	After running `bun run build`:
#297
#298	```
#299	/public/
#300	├── index.json (Main agent index - English)
#301	├── index.zh-CN.json (Chinese index)
#302	├── index.ja-JP.json (Japanese index)
#303	└── agents/
#304	├── airdrop-hunter.json
#305	├── airdrop-hunter.ar.json
#306	└── ... (all agents × 18 languages)
#307	```
#308
#309	> \[!IMPORTANT]: Don't commit `/public` to Git. It's automatically generated during deployment.
#310
#311	---
#312
#313	## Configuration
#314
#315	### Translation Configuration (`.i18nrc.js`)
#316
#317	The workflow is configured via `.i18nrc.js`:
#318
#319	```javascript
#320	module.exports = {
#321	// Fields to translate
#322	selectors: [
#323	'meta.title',
#324	'meta.description',
#325	'meta.tags',
#326	'meta.category',
#327	'config.systemRole',
#328	'config.openingMessage',
#329	'config.openingQuestions',
#330	'examples',
#331	'summary',
#332	],
#333
#334	// Source language
#335	entryLocale: 'en-US',
#336
#337	// Target languages (18 total)
#338	outputLocales: [
#339	'en-US',
#340	'ar',
#341	'bg-BG',
#342	'zh-TW',
#343	'ru-RU',
#344	'ja-JP',
#345	'zh-CN',
#346	'ko-KR',
#347	'fr-FR',
#348	'tr-TR',
#349	'es-ES',
#350	'pt-BR',
#351	'de-DE',
#352	'it-IT',
#353	'nl-NL',
#354	'pl-PL',
#355	'vi-VN',
#356	'fa-IR',
#357	],
#358
#359	// OpenAI model configuration
#360	modelName: 'gpt-4.1-nano',
#361	temperature: 0.5,
#362	concurrency: 18,
#363	};
#364	```
#365
#366	### What Gets Translated
#367
#368	The following fields are automatically extracted and translated:
#369
#370	\| Field \| Description \| Example \|
#371	\| ------------------------- \| ------------------------ \| ----------------------------------- \|
#372	\| `meta.title` \| Agent display name \| "DeFi Yield Farmer" \|
#373	\| `meta.description` \| Short description \| "Optimize yield farming strategies" \|
#374	\| `meta.tags` \| Searchable keywords \| \["defi", "yield", "farming"] \|
#375	\| `meta.category` \| Agent category \| "defi", "programming", etc. \|
#376	\| `config.systemRole` \| Main prompt/instructions \| "You are an expert..." \|
#377	\| `config.openingMessage` \| Welcome message \| "Hello! I can help you..." \|
#378	\| `config.openingQuestions` \| Suggested questions \| \["How do I...", "What is..."] \|
#379	\| `examples` \| Conversation examples \| User/assistant dialogues \|
#380	\| `summary` \| Extended description \| Full agent capabilities \|
#381
#382	### What Does NOT Get Translated
#383
#384	- `identifier`: File name identifier (e.g., `defi-yield-farmer`)
#385	- `author`: GitHub username
#386	- `schemaVersion`: Version number
#387	- `createdAt`: Timestamp
#388	- `avatar`: Emoji or icon
#389	- `homepage`: URL
#390	- Role fields in examples: `"role": "user"`, `"role": "assistant"` remain in English
#391
#392	---
#393
#394	## Running the Workflow
#395
#396	### Available Commands
#397
#398	```bash
#399	# Main workflow commands
#400	bun run format # Format agents + translate to 18 languages
#401	bun run build # Build public distribution
#402	bun run test # Validate agent JSON structure
#403
#404	# Translation-specific commands
#405	bun run i18n:validate # Check translation language accuracy
#406	bun run i18n:fix # Validate and fix translation issues
#407	bun run i18n:clean # Remove invalid translation files
#408
#409	# Development commands
#410	bun run lint # Lint TypeScript files
#411	bun run type-check # TypeScript type checking
#412	bun run prettier # Format all code files
#413	```
#414
#415	### Typical Development Workflow
#416
#417	1. Create or edit an agent
#418
#419	```bash
#420	vim src/my-new-agent.json
#421	```
#422
#423	2. Format and translate
#424
#425	```bash
#426	bun run format
#427	```
#428
#429	- Watch for console output
#430	- Check for any translation errors
#431	- Review generated files in `/locales`
#432
#433	3. Validate translations
#434
#435	```bash
#436	bun run i18n:validate
#437	```
#438
#439	- Ensures translations are in correct language
#440	- Reports confidence scores
#441
#442	4. Build distribution
#443
#444	```bash
#445	bun run build
#446	```
#447
#448	- Creates `/public` directory
#449	- Ready for deployment
#450
#451	5. Commit changes
#452	```bash
#453	git add .
#454	git commit -m "feat: add my-new-agent with 18 language support"
#455	git push
#456	```
#457
#458	---
#459
#460	## Understanding the Process
#461
#462	### Translation Pipeline
#463
#464	The translation system uses OpenAI's GPT models with specialized prompts:
#465
#466	1. Extract: Identifies translatable fields based on `.i18nrc.js` selectors
#467	2. Prepare: Structures content as JSON for AI processing
#468	3. Translate: Calls OpenAI with language-specific instructions
#469	4. Parse: Converts AI response back to JSON (with fallback parsing)
#470	5. Merge: Combines translations with existing content
#471	6. Validate: Verifies translation language accuracy
#472	7. Save: Writes locale-specific files
#473
#474	### OpenAI Translation Prompt
#475
#476	The system uses this specialized prompt:
#477
#478	```
#479	Translate the i18n JSON file to {target_language} according to BCP 47 standards.
#480
#481	Rules:
#482	- Keep key names unchanged
#483	- Output must be valid JSON
#484	- Keep "role" fields unchanged (user, assistant, system, function)
#485	- Only translate "content" fields and text content
#486	- Return only JSON, no explanations
#487	```
#488
#489	### Incremental Translation
#490
#491	The system intelligently handles updates:
#492
#493	- First Run: Translates all fields for all languages
#494	- Subsequent Runs: Only translates new or modified fields
#495	- Merge Strategy: Uses `lodash.merge` to combine old + new translations
#496	- Cost Optimization: Avoids re-translating existing content
#497
#498	Example:
#499
#500	```javascript
#501	// First format run
#502	{
#503	"meta.title": "DeFi Farmer",
#504	"meta.description": "Optimize yields"
#505	}
#506	// → Translates both fields to 18 languages
#507
#508	// You add a new field
#509	{
#510	"meta.title": "DeFi Farmer",
#511	"meta.description": "Optimize yields",
#512	"config.openingMessage": "Hello!" // NEW
#513	}
#514	// → Only translates openingMessage to 18 languages
#515	// → Keeps existing translations for title and description
#516	```
#517
#518	---
#519
#520	## Translation Features
#521
#522	### 1. Automatic Content Generation
#523
#524	If your agent is missing content, the workflow auto-generates:
#525
#526	- Category: AI determines the best category (defi, programming, etc.)
#527	- Summary: Extended description of capabilities
#528	- Examples: Sample conversation dialogues
#529	- Opening Message: Welcome message for users
#530	- Opening Questions: Suggested starter questions
#531
#532	### 2. Intelligent Retries
#533
#534	- Max Retries: 4 attempts per API call
#535	- Exponential Backoff: Automatic retry with delays
#536	- Dirty JSON Parsing: Fallback parser if AI returns invalid JSON
#537
#538	### 3. Concurrent Processing
#539
#540	- Concurrency: 18 parallel translation jobs
#541	- Efficiency: Translates all languages simultaneously
#542	- Speed: Completes 18 languages in \~30-60 seconds per agent
#543
#544	### 4. Language Detection
#545
#546	Uses the `@yutengjing/eld` library to verify:
#547
#548	- Translation is in the correct language
#549	- Confidence score meets threshold
#550	- Flags mismatched languages
#551
#552	### 5. Ignore List
#553
#554	Create `.i18nignore` to skip problematic files:
#555
#556	```
#557	# Skip validation for specific files
#558	locales/my-agent/index.ar.json
#559	locales/another-agent/index.fa-IR.json
#560	```
#561
#562	---
#563
#564	## Validation & Quality Control
#565
#566	### Translation Validation
#567
#568	```bash
#569	bun run i18n:validate
#570	```
#571
#572	Checks each translation file:
#573
#574	- ✅ Detects actual language of content
#575	- ✅ Compares against expected language code
#576	- ✅ Reports confidence scores (0-1)
#577	- ✅ Identifies mismatched languages
#578
#579	Example output:
#580
#581	```
#582	✓ locales/airdrop-hunter/index.zh-CN.json [Confidence: 0.95]
#583	✗ locales/airdrop-hunter/index.ar.json [MISMATCH: Expected ar, got en]
#584	```
#585
#586	### Fix Mode
#587
#588	```bash
#589	bun run i18n:fix
#590	```
#591
#592	- Validates all files
#593	- Attempts to recover from issues
#594	- Re-translates failed files
#595	- Updates ignore list for persistent failures
#596
#597	### Clean Mode
#598
#599	```bash
#600	bun run i18n:clean
#601	```
#602
#603	- Validates all files
#604	- Deletes files that fail validation
#605	- Removes low-confidence translations
#606	- Use with caution!
#607
#608	---
#609
#610	## GitHub Actions Integration
#611
#612	### Automated Workflow
#613
#614	The project includes `.github/workflows/format.yml` that:
#615
#616	1. Triggers on Pull Requests
#617	2. Installs Bun and dependencies
#618	3. Runs `bun run format` with OpenAI API
#619	4. Validates translations with `bun run i18n:fix`
#620	5. Auto-commits changes back to the PR
#621
#622	### Workflow File
#623
#624	```yaml
#625	name: Format
#626
#627	on:
#628	pull_request:
#629	workflow_dispatch:
#630
#631	jobs:
#632	update-i18n:
#633	runs-on: ubuntu-latest
#634	steps:
#635	- uses: actions/checkout@v4
#636
#637	- name: Install bun
#638	uses: oven-sh/setup-bun@v1
#639
#640	- name: Install deps
#641	run: bun i
#642
#643	- name: Run format
#644	run: bun run format
#645	env:
#646	OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
#647	OPENAI_PROXY_URL: ${{ secrets.OPENAI_PROXY_URL }}
#648
#649	- name: Run fix
#650	run: bun run i18n:fix
#651
#652	- name: Commit changes
#653	run: \|
#654	git config user.name "bot"
#655	git config user.email "bot@users.noreply.github.com"
#656	git add .
#657	git commit -m "🤖 chore: Auto format and add i18n json files"
#658	git push
#659	```
#660
#661	### Required Secrets
#662
#663	Set these in your GitHub repository settings:
#664
#665	\| Secret \| Purpose \| Required \|
#666	\| ------------------ \| ------------------------- \| ----------- \|
#667	\| `OPENAI_API_KEY` \| OpenAI API authentication \| ✅ Yes \|
#668	\| `OPENAI_PROXY_URL` \| Custom OpenAI endpoint \| ❌ Optional \|
#669	\| `GH_TOKEN` \| Git push permissions \| ✅ Yes \|
#670
#671	---
#672
#673	## Troubleshooting
#674
#675	### Issue: "OPENAI_API_KEY is not set"
#676
#677	Cause: Environment variable is missing
#678
#679	Solution:
#680
#681	```bash
#682	# Create .env file
#683	echo "OPENAI_API_KEY=sk-your-key" > .env
#684
#685	# Or export directly
#686	export OPENAI_API_KEY=sk-your-key
#687	```
#688
#689	### Issue: Translation API fails repeatedly
#690
#691	Cause: Rate limiting, invalid API key, or network issues
#692
#693	Solutions:
#694
#695	1. Check API key validity
#696	2. Verify API credits remaining
#697	3. Check `OPENAI_PROXY_URL` if using custom endpoint
#698	4. Reduce concurrency in `.i18nrc.js`:
#699	```javascript
#700	concurrency: 5, // Lower from 18
#701	```
#702
#703	### Issue: Translation is in wrong language
#704
#705	Cause: AI model generated incorrect language
#706
#707	Solutions:
#708
#709	1. Run validation:
#710	```bash
#711	bun run i18n:validate
#712	```
#713	2. Check confidence scores
#714	3. Re-translate specific agent:
#715	```bash
#716	# Delete locale folder and re-run
#717	rm -rf locales/agent-name/
#718	bun run format
#719	```
#720
#721	### Issue: JSON parsing errors
#722
#723	Cause: AI returned invalid JSON
#724
#725	Solution: The system has automatic fallbacks:
#726
#727	1. Standard JSON.parse()
#728	2. Dirty JSON parser (lenient parsing)
#729	3. Logs the raw response for debugging
#730
#731	Check console output for details.
#732
#733	### Issue: Translations are incomplete
#734
#735	Cause: Process was interrupted or API failed
#736
#737	Solution:
#738
#739	```bash
#740	# Re-run format (incremental detection will only translate missing)
#741	bun run format
#742
#743	# Or delete locale folder to start fresh
#744	rm -rf locales/agent-name/
#745	bun run format
#746	```
#747
#748	### Issue: Exceeding OpenAI costs
#749
#750	Cause: Large agents or many agents
#751
#752	Solutions:
#753
#754	1. Use a more cost-effective model:
#755	```javascript
#756	// .i18nrc.js
#757	modelName: 'gpt-3.5-turbo', // Cheaper than gpt-4
#758	```
#759	2. Reduce unnecessary text in `systemRole`
#760	3. Process agents individually:
#761	```bash
#762	# Temporarily move agents out of /src
#763	mkdir temp && mv src/*.json temp/
#764	# Move back one agent at a time
#765	mv temp/my-agent.json src/
#766	bun run format
#767	```
#768
#769	---
#770
#771	## Advanced Topics
#772
#773	### Custom Translation Models
#774
#775	Edit `.i18nrc.js` to use different models:
#776
#777	```javascript
#778	module.exports = {
#779	modelName: 'gpt-4-turbo', // More accurate
#780	// modelName: 'gpt-3.5-turbo', // More cost-effective
#781	// modelName: 'gpt-4o', // Latest model
#782	temperature: 0.5, // Lower = more consistent
#783	concurrency: 18, // Parallel jobs
#784	};
#785	```
#786
#787	### Adding New Languages
#788
#789	To add a new language:
#790
#791	1. Edit `.i18nrc.js`:
#792
#793	```javascript
#794	outputLocales: [
#795	'en-US',
#796	// ... existing languages
#797	'hi-IN', // Add Hindi
#798	],
#799	```
#800
#801	2. Run format:
#802
#803	```bash
#804	bun run format
#805	```
#806
#807	3. Verify language detection works:
#808	```bash
#809	bun run i18n:validate
#810	```
#811
#812	### Translation Field Customization
#813
#814	Customize which fields get translated:
#815
#816	```javascript
#817	// .i18nrc.js
#818	selectors: [
#819	'meta.title',
#820	'meta.description',
#821	'config.systemRole',
#822	// Add custom fields:
#823	'customField.text',
#824	'additionalPrompts.greeting',
#825	],
#826	```
#827
#828	### Manual Translation Override
#829
#830	To provide manual translations:
#831
#832	1. Run format to generate all files
#833	2. Edit specific locale file manually:
#834	```bash
#835	vim locales/my-agent/index.fr-FR.json
#836	```
#837	3. Add to ignore list to prevent overwrite:
#838	```bash
#839	echo "locales/my-agent/index.fr-FR.json" >> .i18nignore
#840	```
#841
#842	### Debugging Translation Issues
#843
#844	Enable debug mode:
#845
#846	```bash
#847	DEBUG=true bun run format
#848	```
#849
#850	View detailed logs:
#851
#852	- OpenAI API requests
#853	- Response parsing
#854	- Merge operations
#855	- File operations
#856
#857	---
#858
#859	## Best Practices
#860
#861	### 1. Write Clear English Source Content
#862
#863	Good translations start with clear source text:
#864
#865	- ✅ Use simple, direct language
#866	- ✅ Avoid idioms and slang
#867	- ✅ Be specific and technical when needed
#868	- ❌ Don't use ambiguous phrasing
#869
#870	### 2. Test After Changes
#871
#872	Always validate after updates:
#873
#874	```bash
#875	bun run format && bun run i18n:validate && bun run build
#876	```
#877
#878	### 3. Monitor API Costs
#879
#880	- Track OpenAI API usage
#881	- Use cheaper models for testing
#882	- Process agents incrementally for large changes
#883
#884	### 4. Commit Locale Files
#885
#886	- ✅ Commit all `/locales` files to Git
#887	- ✅ Track translation changes in PRs
#888	- ✅ Review AI-generated translations
#889
#890	### 5. Version Control
#891
#892	When updating an agent:
#893
#894	```bash
#895	# Before changes
#896	git add src/my-agent.json
#897
#898	# After format
#899	git add locales/my-agent/
#900	git commit -m "feat: update my-agent + translations"
#901	```
#902
#903	---
#904
#905	## Summary
#906
#907	The 18 Languages i18n workflow provides:
#908
#909	- 🌍 Automatic translation to 18 languages
#910	- 🚀 Fast processing with concurrent API calls
#911	- 💰 Cost-effective with incremental updates
#912	- ✅ Quality assurance with language validation
#913	- 🔄 CI/CD integration with GitHub Actions
#914	- 📦 CDN-ready output for global distribution
#915
#916	Simply create your agent in English, run `bun run format`, and your agent is instantly available to users worldwide in their native language.
#917
#918	---
#919
#920	## Additional Resources
#921
#922	- [OpenAI API Documentation](https://platform.openai.com/docs)
#923	- [BCP 47 Language Tags](https://www.rfc-editor.org/info/bcp47)
#924	- [Contributing Guide](./CONTRIBUTING.md)
#925	- [Agent Guide](./AGENT_GUIDE.md)
#926	- [Troubleshooting](./TROUBLESHOOTING.md)
#927
#928	---
#929
#930	Questions or Issues?
#931
#932	- 📝 Open an issue on GitHub
#933	- 💬 Check [FAQ.md](./FAQ.md)
#934	- 🐛 Report bugs with detailed logs
#935
#936
#937

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public