번역 범위

증분 업데이트, 대상 로캘의 포함 범위, 의도적인 새로 고침을 구분해 파일과 고정 키를 선택하세요.

로컬라이제이션 변경은 파일, 언어 또는 메시지 집합에 영향을 줄 수 있습니다. CLI에서는 이를 각각 다른 방식으로 선택합니다. 프로젝트 설정으로 파일과 대상 로캘을 선택하고, 위치 인수 패턴으로 파일 범위와 변경 계획을 좁히며, --key로 고정 키를 기준으로 메시지를 선택합니다.

파일 범위에 따라 계획이 달라집니다 #

sh
lingo push 'locales/en.json' --wait

패턴은 설정된 소스 파일의 범위를 좁힙니다. 소스와 대상이 별도 파일인 형식에서는 이 명령이 누락된 대상 파일을 생성하고, 소스가 변경되었더라도 기존 대상 파일은 그대로 둡니다. 설정된 로캘 중 작업에서 제외되는 로캘이 있으면, 나중에 일반 푸시로 해당 수정 사항을 처리할 수 있도록 기존 소스 기준 상태를 유지합니다. 기준 상태가 없으면 초기화할 수 있습니다.

일상적인 소스 수정에는 별도 옵션 없이 lingo push --wait를 사용하세요. 소스와 대상이 별도 파일인 형식에서 파일 전체를 의도적으로 교체하려면 --force와 함께 위치 인수로 범위를 지정하세요. 강제 실행하면 기존 대상의 맥락이 사라진다는 점에 유의하세요. 엑스씨스트링스 카탈로그에서는 내장된 번역을 계속 재사용할 수 있습니다. 카탈로그 업데이트를 참고하세요. 대상은 항상 targetLocales에서 가져오며, 푸시에는 --locale 또는 --target-locale 플래그가 없습니다.

고정 키 새로 고침 #

sh
lingo push 'locales/en.json' --key 'checkout.title' --key 'checkout.submit' --wait

여러 항목을 선택하려면 --key를 반복해서 지정하세요. 키는 checkout.title 또는 items[0].title처럼 점이나 대괄호로 구분한 경로이며, 객체를 선택하면 그 아래의 모든 문자열이 포함됩니다. 따라서 auth.login는 auth.login.title를 포함하지만 auth.login_url는 선택하지 않습니다. *는 경로 구간 하나 전체를, []는 모든 배열 항목을 나타냅니다. auth.log*와 같은 부분 와일드카드는 허용되지 않습니다. $. 또는 $[로 시작하는 패턴은 제이슨패스 쿼리로 그대로 전달됩니다. 와일드카드 패턴은 따옴표로 감싸세요.

이전 CLI에서 /를 사용해 작성한 패턴도 사용할 수 있습니다. /가 포함된 패턴은 /에서만 나뉘며, 각 이름은 하나의 완전한 이름으로 처리됩니다. auth/login는 auth.login와 같은 키를 선택하고, common/error.message는 common 아래의 error.message 키를 선택합니다. legal/Terms%20of%20use처럼 퍼센트 인코딩된 이름은 디코딩됩니다. /가 없는 패턴은 점으로 구분한 경로로 처리되며 디코딩되지 않으므로, 인코딩된 이름 하나를 지정하려면 $['Terms of use']처럼 제이슨패스로 작성하세요. /가 포함된 모든 패턴은 이 방식으로 해석되므로, 이름에 /가 포함된 키는 $.routes['/about'].title처럼 제이슨패스를 사용해야 합니다. 이 형식에서 *는 이름 하나 전체를 나타냅니다. auth/*처럼 끝에 붙는 *는 이전 CLI와 마찬가지로 auth 바로 아래의 값을 선택하지만, 그 안에 중첩된 객체나 배열은 선택하지 않습니다. 끝에 붙는 /**는 그 앞의 이름 아래에 있는 모든 항목을 포함합니다. auth/**는 auth와 같으며, auth/*/**는 auth/*가 제외하는 auth 아래의 객체와 배열도 포함합니다. items/0와 같은 숫자는 문서 구조에 따라 배열 항목이나 객체 키 "0"를 선택합니다. 이름 안의 글로브, 끝이 아닌 위치의 **, 대괄호, a//b와 같은 빈 이름은 허용되지 않습니다.

형식키 범위
JSON/JSONC, PHP, 타입스크립트, 자바 프로퍼티소스 값이 변경되지 않은 문자열까지 포함해 선택한 문자열을 다시 생성합니다.
YAML/루트 키 YAML고정 키를 선택하되, 선택한 문자열이 변경되지 않았다면 기존 번역을 재사용할 수 있습니다.
겟텍스트, ARB, 애플 스트링스, 엑스씨스트링스, CSV, 안드로이드, XLIFF지원되지 않습니다. --key를 사용하면 오류가 발생하고 푸시가 중단됩니다.
마크다운, MDX, 마크독, HTML, 오픈에이피아이 YAML, 서브립, 일반 텍스트, 애플 스트링스딕트고정 키가 없어 메시지를 표시하고 건너뜁니다.

키 새로 고침에는 기존 대상이 필요합니다. 누락된 로캘과 고정 키가 없는 형식은 새로 생성하지 않고 메시지를 표시한 뒤 건너뜁니다. 누락 파일 채우기는 누락된 일반 파일을 생성할 뿐, 기존 파일 안의 누락 항목을 채우지는 않습니다. --force를 추가해도 키 범위에 따른 계획은 달라지지 않으며 YAML의 기존 번역 재사용도 막지 않습니다.

push --wait로 수집하든 별도의 풀로 수집하든, 키 새로 고침은 전체 소스의 기준 상태를 변경하지 않습니다. 따라서 아직 처리되지 않은 일반 소스 수정 사항은 다음 일반 푸시에서도 처리됩니다.

지침 변경 후 새로 고침 #

로컬라이제이션 엔진의 용어집이나 규칙을 수정해도 소스 파일의 바이트는 바뀌지 않습니다. 따라서 일반 푸시로는 아무 작업도 수행되지 않을 수 있습니다. JSON, JSONC, 타입스크립트, PHP에서는 영향을 받는 고정 키를 선택하세요. YAML에서는 원하는 부분만 정확히 수정하려면 대상을 직접 편집하세요. 또는 확정된 대상을 저장한 뒤, --key 없이 범위를 지정한 전체 파일 --force를 사용해 다시 생성하세요. 이 교체 작업은 주변 메시지도 바꿀 수 있으므로 결과 파일 전체를 확인하세요. 키 제어는 재구성할 때 어떤 소스 값이나 대상 값을 유지할지 결정하며, 작업 범위를 선택하지는 않습니다.

변경 규모가 크다면 검토하고 복구할 수 있을 만큼 범위를 좁힌 뒤, 제출하기 전에 예상 사용량을 확인하세요. 예상 사용량을 확인하면 필요한 파일이 업로드되고 작업 계획이 수립되지만, 번역 작업은 생성되지 않습니다.

단일 로캘 다시 번역하기 #

언어마다 별도 파일을 사용하는 프로젝트에서는 해당 언어의 대상 파일을 삭제한 뒤 누락된 파일을 채우세요. 먼저 보류 중인 소스 업데이트를 마치고 확정된 번역을 저장하세요. 필터를 적용해 삭제하면 다른 언어의 소스 기준 상태와 Lockfile 항목은 유지됩니다.

locales/en.json에 설정된 소스가 있다면 프랑스어 대상 파일 삭제를 미리 확인하세요.

sh
lingo purge --locale fr --file locales/en.json

표시된 경로를 확인하세요. 삭제하려는 대상 파일이 맞다면 삭제를 확정하고 누락된 번역을 생성하세요.

sh
lingo purge --locale fr --file locales/en.json --yes
lingo push --backfill-missing --wait

locales/en/*.json처럼 글로브를 사용하는 설정에서는 두 삭제 명령 모두에 --file 옵션을 반복해서 지정해 구체적인 소스 경로를 전달하세요. 삭제 명령 자체는 글로브를 확장하지 않습니다. 프랑스어 대상 파일을 다시 생성하려는 모든 소스를 포함하세요. 누락 파일 채우기는 설정된 대상 중 누락된 파일을 모두 생성하므로, 실행하기 전에 다른 대상 파일이 누락되지 않았는지 확인하세요.

완료되면 프랑스어 결과물을 확인하고 업데이트된 Lockfile과 함께 커밋하세요. 다른 언어의 기존 대상 파일은 변경되지 않습니다. 선택 규칙은 삭제를 참고하세요. 이 절차는 소스와 모든 대상 로캘이 하나의 파일을 공유하는 엑스씨스트링스 카탈로그에는 적용되지 않습니다.