최신 CLI로 마이그레이션
승인된 번역과 정상 작동하는 애플리케이션은 유지하면서 기존 버킷과 소스 지문을 교체하세요.
최신 @lingo.dev/cli는 서버 측 푸시·풀 작업과 .lingo 프로젝트 상태를 사용합니다. 이전 lingo.dev 패키지는 로컬 버킷 처리, i18n.json, i18n.lock를 사용합니다. 마이그레이션은 단순히 명령어 이름을 바꾸는 것이 아니라, 프로젝트에 필요한 동작을 유지하는 작업입니다.
정상 작동하는 초기 상태 보존 #
설치된 버전을 기록하고 소스, 승인된 대상 번역, 설정, 이전 Lockfile을 버전 관리에 보관하세요. 애플리케이션이 해당 대상 번역을 불러오는지도 확인하세요. 범위를 한정해 교체한 구성이 정상 작동할 때까지는 기존 로컬라이제이션 구성의 라우터, 프로바이더, 언어 전환기, 카탈로그 로더를 유지하세요.
프레임워크와 런타임 버전, 필요한 소스 로캘, 대상 로캘, 기본 로캘을 기록하세요. 대표적인 로캘 접두사 경로, 초기 감지, 폴백, 언어 전환을 테스트하세요. 이러한 애플리케이션 점검은 파일 번역 마이그레이션과 별도로 진행하세요.
파일 선택 재구성 #
소스·대상 로캘과 명시적인 파일 항목을 지정해 .lingo/config.json를 만든 다음, 사용 권한이 있는 조직과 로컬라이제이션 엔진을 연결하세요. 기존 버킷과 지문은 이름만 바꿔서는 이 스키마로 전환할 수 없습니다.
현재 CLI 설정은 HTML(.html 및 .htm), 일반 텍스트(.txt, 버전 0과 동일하게 한 줄에 단위 하나씩 저장), 한 파일에 모든 로캘을 열별로 저장하는 CSV 표, 자바 .properties 파일 등 22가지 형식을 지원합니다. 자바 파일은 버전 0과 동일하게 키마다 단위 하나를 저장하고, lockedKeys, preservedKeys, ignoredKeys도 버전 0과 같은 방식으로 매칭합니다. lockedPatterns에는 전후방 탐색과 역참조를 지원하지 않는 RE2 구문을 사용합니다. 버전 0의 csv 버킷 파일을 옮기기 전에 CSV 레이아웃과 대조해 확인하세요. 버전 0의 properties 버킷 경로는 자바 프로퍼티를 기준으로 확인하세요. messages_[locale].properties 같은 [locale] 파일 이름은 messages_en.properties 같은 소스 패턴으로 바뀝니다. 로캘별 CSV, MJML 등 이전 버전에서만 지원되는 버킷에는 검증된 변환 과정이나 다른 번역 경로가 필요합니다. 정확한 열거형, 매처, 출력 템플릿은 설정에서 확인하세요. 버전 0에서 제공업체에 직접 연결할 때 사용하던 모델, 프롬프트, 기본 URL 설정은 이 프로젝트 스키마에 넣지 않습니다.
설정 범위를 넓히기 전에 선택한 소스 하나와 여기서 파생되는 대상 경로를 확인하세요. 마크다운 계열의 속성에는 translateComponentProps를 사용하세요.
기존 번역 채택 및 업데이트 #
최신 버전에서는 범위 지정·초기화 계획을 통해 기존 대상 번역을 채택할 수 있습니다. 이를 기준 상태로 확정하기 전에 대표 파일과 사람이 수정한 내용을 확인하세요. 파일이 있다는 사실만으로는 값이 최신 소스와 일치하는지 알 수 없습니다.
백필은 누락된 일반 파일을 채우는 반면, v0는 일반적으로 기존 카탈로그 안에서 누락된 키를 채웁니다. 이후의 키 보충 작업에는 최신 버전의 증분 소스 업데이트나 지원되는 키 갱신 기능을 사용하세요. JSON 키의 이름이 바뀌면 텍스트가 이전 키와 같더라도 경로를 기준으로 새 작업으로 처리됩니다. v0에서 콘텐츠 지문으로 이름 변경을 감지해 번역을 재사용하던 동작에 의존하지 마세요.
키가 바뀌지 않았다면 대상 번역의 수정 내용은 증분 작업 중에도 유지할 수 있습니다. 명시적인 키 보존 규칙을 사용하면 소유권을 별도로 선택할 수 있습니다. 파일이 분리된 형식에서는 파일 전체를 강제로 처리할 경우 현재 대상 번역의 문맥이 사라지고 승인된 표현이 바뀔 수 있으므로, 기존 번역을 채택하는 지름길로 사용해서는 안 됩니다.
최신 버전의 첫 실행 완료 #
최신 빠른 시작 가이드에 따라 백필을 수행하고 파일을 가져오는 단계까지 진행하세요. 기준 상태 없이 처음 푸시만 실행하면 초기 번역을 요청하는 대신 소스 바이트를 저장합니다. 파일 워크플로가 완료되었다고 판단하기 전에 기다리거나 풀을 실행하세요.
확정된 소스, 대상, 설정, 현재 Lockfile을 함께 커밋하세요. 최신 실행 포인터는 로컬 홈 디렉터리에만 보관되며 Git을 통해 전달되지 않습니다. 이후 풀 작업에서는 해시를 비교하므로, 내용이 불일치하는 수정 사항을 커밋하는 것만으로는 충돌이 해결되지 않습니다. lingo check는 파일 단위로 기존의 잠금 파일 고정 검사를 대체합니다. .lingo/lock.json 이후 소스가 변경되었거나 대상 파일이 없으면 실패하며, 누락된 Lockfile을 생성하는 일은 없습니다. 커밋된 Lockfile이 없으면 소스 변경을 감지할 수 없으며, 대상 파일이 존재하는지만 확인합니다.
리액트 마이그레이션 #
최신 리액트 워크플로는 리터럴로 작성된 소스·문맥 호출을 JSONC와 선언 파일로 추출하고, 선택한 카탈로그를 번역한 다음 런타임 문자열 맵을 불러옵니다. 변경 범위를 넓히기 전에 컴포넌트 하나에서 폴백, 변수, 로캘 전환, 승인된 표현을 확인하세요.
패키지별 작업은 기존 리액트 메시지 마이그레이션과 리액트를 참고하세요. 함께 제공되는 lingo guide migrate는 설치된 버전을 반영할 뿐, 이전에 생성된 모든 구성과 기능이 동일하다는 뜻은 아닙니다.