my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	---
#2	description:
#3	globs:
#4	alwaysApply: false
#5	---
#6	# I18n Translation System Guide
#7
#8	This project implements an intelligent translation system with incremental detection and language validation.
#9
#10	## 🌍 Translation Workflow
#11
#12	### Core Components
#13	- [scripts/processors/i18n-processor.ts](mdc:scripts/processors/i18n-processor.ts) - Handles OpenAI-based translation
#14	- [scripts/formatters/agent-formatter.ts](mdc:scripts/formatters/agent-formatter.ts) - Manages incremental translation logic
#15	- [scripts/validators/language-validator.ts](mdc:scripts/validators/language-validator.ts) - Validates translation quality
#16
#17	### Translation Process Flow
#18	1. Source Detection: Extract translatable fields from source files
#19	2. Incremental Check: Compare with existing translations to detect changes
#20	3. Translation: Use OpenAI to translate only new/changed content
#21	4. Merge: Combine new translations with existing ones
#22	5. Validation: Verify translation language matches expected locale
#23	6. Format: Apply formatting and save results
#24
#25	## 🔄 Incremental Translation Logic
#26
#27	### Key Method: `getIncrementalData()`
#28	Located in [scripts/formatters/agent-formatter.ts](mdc:scripts/formatters/agent-formatter.ts):
#29
#30	```typescript
#31	private getIncrementalData = (sourceData: any, existingData: any) => {
#32	const needsTranslation = {};
#33	let hasUpdates = false;
#34
#35	for (const key of config.selectors) {
#36	const sourceValue = get(sourceData, key);
#37	const existingValue = get(existingData, key);
#38
#39	if (sourceValue && !isEqual(sourceValue, existingValue)) {
#40	set(needsTranslation, key, sourceValue);
#41	hasUpdates = true;
#42	}
#43	}
#44
#45	return { hasUpdates, needsTranslation };
#46	};
#47	```
#48
#49	### Translation Strategy
#50	- Full Translation: When no existing translation file exists
#51	- Incremental Translation: When changes detected in source content
#52	- Skip Translation: When no changes detected (content unchanged)
#53	- Merge Results: Combine new translations with existing using `lodash.merge`
#54
#55	## 🛡️ Language Validation
#56
#57	### Validation Process
#58	Uses `@yutengjing/eld` library for language detection:
#59
#60	```typescript
#61	import { validateTranslationLanguage } from '../validators/language-validator';
#62
#63	const validationResult = validateTranslationLanguage(
#64	translatedData,
#65	expectedLocale,
#66	fileName
#67	);
#68	```
#69
#70	### Validation Command
#71	Use [scripts/commands/validate-language.ts](mdc:scripts/commands/validate-language.ts):
#72
#73	```bash
#74	pnpm run validate:lang # Validate all files
#75	pnpm run validate:lang --delete # Validate and delete invalid files
#76	pnpm run validate:lang <file_path> # Validate single file
#77	```
#78
#79	## 📋 Configuration
#80
#81	### Translation Fields
#82	Defined in [scripts/core/constants.ts](mdc:scripts/core/constants.ts) as `config.selectors`:
#83	- `meta.title`
#84	- `meta.description`
#85	- `meta.tags`
#86	- `config.systemRole`
#87	- `summary`
#88	- `examples`
#89	- `config.openingMessage`
#90	- `config.openingQuestions`
#91
#92	### Supported Locales
#93	Available in `config.outputLocales`:
#94	- `zh-CN`, `en-US`, `ja-JP`, `ko-KR`
#95	- `fr-FR`, `de-DE`, `es-ES`, `pt-BR`
#96	- `ru-RU`, `it-IT`, `nl-NL`, `pl-PL`
#97	- `ar`, `tr-TR`, `vi-VN`, `ms-MY`
#98	- `th-TH`, `hi-IN`, `bg-BG`, `cs-CZ`
#99	- `da-DK`, `fi-FI`, `he-IL`, `hu-HU`
#100	- `id-ID`, `no-NO`, `ro-RO`, `sk-SK`
#101	- `sl-SI`, `sv-SE`, `uk-UA`
#102
#103	## 🚀 Best Practices
#104
#105	### OpenAI Translation Prompts
#106	- Preserve role fields (`user`, `assistant`, `system`, `function`)
#107	- Translate only content fields, not structural elements
#108	- Maintain JSON structure and format
#109	- Follow BCP 47 language standards
#110
#111	### Error Handling
#112	- Use dirty-json as fallback for malformed JSON responses
#113	- Log translation failures with detailed error information
#114	- Gracefully handle API rate limits and timeouts
#115
#116	### File Management
#117	- Create locale directories as needed
#118	- Use consistent file naming: `agent-id.locale.json`
#119	- Clean up empty JSON files automatically
#120
#121
#122
#123

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public