Intlayer에서 소스 문자열 호출로 마이그레이션
Intlayer는 유형화된 콘텐츠 사전 또는 번역 관리 시스템을 통해 번역을 관리하는 애플리케이션에 이상적입니다. ai-i18n-tools는 t('English source')와 같은 소스 문자열 호출을 사용하는 코드와 같은 다른 워크플로를 대상으로 합니다. t() 내부의 문자열은 어떤 언어든 될 수 있는 sourceLocale로 작성됩니다. 이 예시들에서 영어는 단지 예시일 뿐입니다. 해당 소스 문자열을 코드에 직접 유지함으로써, 이 접근 방식은 유지 관리를 단순화하고 복잡성을 줄입니다. 이 모델이 귀하의 요구 사항에 부합할 때, migrate-intlayer는 기존 사전을 가져오고 호환 가능한 호출 사이트를 자동으로 다시 작성합니다. 나머지 사이트는 변경되지 않은 상태로 두고, 특정 교체 지침이 포함된 보고서를 생성하여, 마이그레이션을 단계별로 완료하거나 보고서를 AI 코딩 에이전트에게 제공하여 귀하를 위해 마이그레이션을 완료하도록 할 수 있습니다.
이미 i18next JSON 번역 파일을 사용하고 계신가요? 이 마이그레이션 명령어는 필요하지 않습니다. 대신 JSON 파이프라인을 사용하십시오.
인플레이스 번역 또는 마이그레이션?
이 페이지에서는 앱을 Intlayer에서 ai-i18n-tools의 t('English source')과 같은 소스 문자열 t() 호출로 전환하는 방법을 설명합니다. 문자열은 sourceLocale로 작성되며, 이는 모든 언어가 될 수 있습니다. 런타임에 Intlayer를 유지하고 누락된 번역만 채우려면 대신 translate-intlayer를 사용하세요. 이 도구는 *.content.ts를 인플레이스 방식으로 번역합니다.
migrate-intlayer의 기능
*.content.ts기본 내보내기를 구문 분석합니다(key+content+t({ locale: '…' })리프).- 소스 로케일 텍스트와 사전에 이미 있는 번역을 기반으로
ui.stringsJson및ui.flatOutputDir아래의 로케일별 파일을 시딩합니다. 가져온 행에는models필드가 없습니다(이 실행에서 기계 번역되지 않음). - 안전한 호출 사이트를 다시 작성합니다:
binding.path.to.leaf.value→t('English source')binding.path.value.replace('{token}', expr)→t('English {{token}}', { token: expr })
- 나머지 모든 항목(동적 키, JSX 스프레드, 체인
.replace().replace(), 구조 분해)은 변경하지 않고 그대로 둡니다. 보고서는 정확한 표현식, 구체적인t()또는 JSX 대체 항목, 추가할import { t } from '…';줄과 함께 이러한 각 사이트를 나열합니다. - 기본적으로 드라이 런을 실행합니다. 카탈로그 시딩 및 안전한 재작성을 적용하려면
--write을(를) 전달하십시오. 보고서는 항상 작성됩니다. 또한 수동 재작성 후 삭제할 사전 파일과 남은useIntlayer/IntlayerProvider사용법, 여전히extract그 다음translate-ui이(가) 필요한 카탈로그 키, 앱의 i18n 모듈에 붙여넣을 런타임 부트스트랩을 나열합니다.
프로젝트 마이그레이션
ai-i18n-tools설치(설치 참조). 프로젝트에 아직ai-i18n-tools.config.json이(가) 없다면 스캐폴딩합니다:bashai-i18n-tools init -P gemini
Intlayer 사전에 이미 있는 로캘과 일치하도록 sourceLocale 및 targetLocales을(를) 편집하고, ui.sourceRoots, ui.stringsJson, ui.flatOutputDir을(를) 앱의 소스 및 원하는 카탈로그 경로를 가리키도록 설정합니다. 이는 translate-ui에서 사용하는 키와 동일합니다. UI 문자열 — 1단계: 초기화를 참조하세요. 2. 먼저 드라이 런을 실행합니다: ai-i18n-tools migrate-intlayer (--write 없음). 파일 변경 전에 어떤 항목을 찾았는지, 어떤 호출 사이트가 수동 검토가 필요한지 확인하려면 migrate-intlayer-report.md을(를) 읽어보세요. 3. ui.stringsJson / ui.flatOutputDir을(를) 시드하고 안전한 호출 사이트를 다시 작성하려면 ai-i18n-tools migrate-intlayer --write을(를) 실행합니다. 4. 재생성된 보고서 migrate-intlayer-report.md을(를) AI 코딩 에이전트에게 전달하거나(권장), 다음 단계에 따라 직접 처리합니다.
- 보고서는 단계별 TODO로 끝납니다. 여기에 표시된 구체적인
t('…')/JSX로 각 수동 검토 사이트를 완료하고,import { t } from '…';줄을 추가한 다음, 보고서에 나열된 남은*.content.ts파일과useIntlayer/IntlayerProvider사용을 삭제합니다.- 보고서의 런타임 부트스트랩을 앱의 i18n 모듈 위에 붙여넣습니다. 로캘 제어에서
loadLocale(next)을(를) 호출한 다음i18n.changeLanguage(next)을(를) 호출합니다.loadLocale은(는) 플랫 번들만 등록하고 활성 언어를 전환하지 않습니다. - 보고서에서 새 문자열로 표시된 모든 소스 문자열에 대해
ai-i18n-tools extract을(를) 실행한 다음ai-i18n-tools translate-ui(또는sync)을(를) 실행합니다.extract은(는) 부트스트랩이 가져오는ui-languages.json도 작성하므로, 새 문자열이 추가되지 않았더라도 앱을 시작하기 전에 실행하세요.strings.json, 플랫 로캘 파일 또는ui-languages.json을(를) 수동으로 편집하지 마세요. 해당 명령어가 이를 관리합니다. - 보고서의 정리 목록이 완료되고 앱이 ai-i18n-tools에서 실행되면
intlayer/react-intlayer종속성과 사전 파일을 제거합니다.
- 보고서의 런타임 부트스트랩을 앱의 i18n 모듈 위에 붙여넣습니다. 로캘 제어에서
예제 실행
위의 단계는 모든 Intlayer 프로젝트에 적용됩니다. intlayer-migration 예제에서는 기본(자동 재작성 가능) 및 복잡한(수동 검토) 사례가 포함된 작은 Vite + React 앱에서 이 단계를 진행하므로, 자체 코드에 적용해 보기 전에 보고서와 런타임 부트스트랩을 확인할 수 있습니다. intlayer-pristine/은(는) 수정되지 않으며, src/이(가) 작업 사본입니다.
npx degit wsj-br/ai-i18n-tools/examples/intlayer-migration intlayer-migration
cd intlayer-migration
pnpm install
pnpm reset
pnpm migrate:dry
pnpm migrate:writeAI 코딩 에이전트에게 migrate-intlayer-report.md을(를) 전달하십시오(또는 플래그가 지정된 파일을 직접 편집하십시오). 보고서에는 src/i18n.ts 위에 붙여넣을 런타임 모듈이 포함되어 있습니다. 로케일 제어에서 loadLocale(next)을(를) 호출한 다음 i18n.changeLanguage(next)을(를) 호출하십시오. loadLocale은(는) 플랫 번들만 등록합니다.
pnpm i18n:sync
pnpm dev먼저 pnpm i18n:sync에서 extract을 실행하면 ui-languages.json가 생성됩니다. 부트스트랩에서 해당 파일을 불러오므로 추출 작업 후에만 앱을 시작하십시오. strings.json, 플랫 로케일 파일 또는 ui-languages.json는 수동으로 편집하지 마십시오.
pnpm reset는 intlayer-pristine/를 src/ 위로 다시 복사하고 생성된 카탈로그를 지워서 다시 시작할 수 있게 합니다.
전체 안내: examples/intlayer-migration/README.md.
명령
ai-i18n-tools migrate-intlayer [paths...] [--write] [--report <path>] [--content-glob <glob>] [--t-import <specifier>]구성에 ui.stringsJson 및 ui.flatOutputDir가 필요합니다(translate-ui와 동일). LLM을 호출하지 않습니다.
| 옵션 | 의미 |
|---|---|
[paths...] | 스캔할 파일/디렉터리/글로브(기본값: ui.sourceRoots) |
--write | 카탈로그를 시드하고 안전한 호출 위치를 다시 작성합니다(기본값: 드라이 런) |
--report <path> | 보고서 경로(기본값: migrate-intlayer-report.md) |
--content-glob <glob> | 사전 파일명 글롭(기본값: **/*.content.ts) |
--t-import <specifier> | 생성된 t()의 가져오기 지정자(기본값: src/i18n.ts가 존재하면 상대적 ./i18n, 그렇지 않으면 i18next) |
--write 실행 후에는 보고서의 수동 검토 사이트 작업을 완료하고, 보고서에 나열된 미사용 *.content.ts 파일 및 IntlayerProvider 래퍼를 삭제한 뒤 런타임 부트스트랩을 붙여넣고 로케일 컨트롤에서 i18n.changeLanguage을 호출하십시오. 보고서에서 신규로 표시된 소스 문자열에 대해 extract를 실행한 다음 translate-ui(또는 sync)를 실행하십시오. extract에서는 ui-languages.json도 생성하며, 부트스트랩에서 이를 불러옵니다. strings.json, 플랫 로케일 파일 또는 ui-languages.json은 수동으로 편집하지 마십시오.
참고 항목: CLI — UI 문자열, i18next 연결