CSV
하나의 파일에서 로캘마다 별도 열을 두고, 원하는 열을 키로 사용하는 CSV 표를 번역하세요.
CSV 번역 표는 원문과 모든 번역을 하나의 파일에서 관리합니다. 메시지마다 한 행을, 로캘마다 한 열을 사용합니다. csv 파일 핸들러는 파일의 대상 로캘 셀을 채운 뒤 원본 경로에 다시 저장합니다. 번역되는 행에서 설명하듯이 대상 로캘 셀만 기록하고, 해당 로캘의 열이 없으면 새로 추가합니다. 다른 열과 행 순서, 따옴표, 줄바꿈 형식은 그대로 유지됩니다. 단, 파일 시작 부분의 UTF-8 바이트 순서 표시는 유지되지 않습니다. 저장된 파일에는 이 표시가 없으므로, 이 표시를 기준으로 UTF-8을 감지하는 스프레드시트 앱에서는 파일을 UTF-8로 지정해 가져와야 할 수 있습니다.
표 구성하기 #
빈 줄이나 공백만 있는 줄을 제외한 첫 번째 줄이 헤더입니다. 각 행을 식별하는 키 열과 원문 열을 하나씩 두고, 대상 로캘마다 별도의 열을 만듭니다.
id,en,notes,de
checkout.title,Complete your order,Shown on the last step,Bestellung abschließen
checkout.pay,"Pay now, or later",,- 로캘 열. 헤더가 로캘 코드와 일치하는 열은 해당 로캘의 열로 인식하며, 대소문자는 구분하지 않습니다.
de와DE는 독일어 열로 인식하지만,de-DE는 다른 로캘입니다. 원문 열의 헤더는 설정에 지정한sourceLocale입니다. - 키 열. 기본적으로 첫 번째 헤더 셀에 적힌 이름이 키 열의 이름이 됩니다. 다른 열을 사용하려면 파일 항목에
keyColumn을 설정하세요. 원문 자체를 키로 쓴다면 원문 열을 키 열로 사용할 수 있습니다. - 기타 열.
notes처럼 키 열도 로캘 열도 아닌 열은 바이트 단위까지 그대로 유지되며, 번역 대상으로 전송되지 않습니다. - 구문. 셀은 쉼표로 구분합니다. 쉼표, 따옴표 또는 줄바꿈이 포함된 셀은 큰따옴표로 감싸고, 셀 안의 따옴표는 두 번 연속으로 씁니다(
""). 세미콜론이나 탭으로 구분된 파일은 지원하지 않습니다.
CSV 번역 설정하기 #
CSV 파일은 파일 항목의 패턴이 .csv로 끝나 형식을 자동으로 판별할 수 있거나, 항목에 "format": "csv"가 설정되어 있을 때만 선택됩니다. "format": "csv"가 설정된 항목은 .csv 파일만 선택합니다. data/**/*처럼 범위가 넓은 패턴이라도 해당 형식을 지정하지 않으면 CSV 파일은 선택되지 않습니다. 따라서 기존 항목이 관련 없는 데이터 파일까지 덮어쓰는 일은 없습니다. 확장자는 대소문자를 구분합니다. 파일 이름이 strings.CSV이면 번역되지 않으므로 strings.csv로 바꾸세요.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "i18n/strings.csv", "keyColumn": "id" }]
}모든 로캘의 번역을 파일 자체에 저장하므로 이 형식에서는 targetPath를 사용할 수 없습니다. CSV 행은 키 제어 설정과 대조하지 않으므로 lockedKeys, preservedKeys, ignoredKeys도 사용할 수 없습니다. CLI 및 GitHub App에서 동일한 설정을 사용할 수 있습니다.
번역되는 행 #
| 행 | 결과 |
|---|---|
| 키와 원문이 있는 행 | 로캘 셀이 비어 있거나 최신 상태가 아니면 번역합니다. |
| 키는 있고 원문 셀은 비어 있는 행 | 그대로 유지하며, 로캘 셀은 변경하지 않습니다. |
| 원문은 있고 키 셀은 비어 있거나 공백만 있는 행 | 그대로 유지하며 번역하지 않습니다. 번역하려면 키를 지정하세요. |
| 키와 원문이 모두 비어 있는 행 또는 빈 줄 | 공백만 있는 줄도 그대로 유지합니다. |
공백만 있는 로캘 셀은 빈 셀로 간주합니다. 마지막 푸시 이후 해당 행의 원문이 바뀌지 않았다면 값이 있는 셀을 재사용합니다. 원문이 바뀌면 해당 행의 모든 로캘 셀을 다시 번역합니다. 마지막 푸시 이후 추가된 행은 값이 있는 셀을 유지하고 빈 셀만 번역합니다. 키가 바뀐 행도 새로 추가된 행으로 간주합니다. 파일을 처음 푸시할 때, CLI --force를 사용할 때, --force 없이 파일을 지정하는 GitHub App 명령을 실행할 때도 값이 있는 셀을 유지합니다. 이전에 푸시한 파일에서 비교에 사용할 원문 열이나 키 열을 하나로 특정할 수 없을 때도 마찬가지입니다. 예를 들어 두 열 중 하나의 이름이 바뀐 경우가 여기에 해당합니다. --force를 지정한 GitHub App 명령은 파일의 모든 행을 다시 번역합니다.
다음 원문은 번역하지 않고 그대로 복사합니다. 100처럼 아스키 숫자 0~9로만 이루어진 값, //로 시작하거나 영문자·숫자·밑줄로 이루어진 스킴 뒤에 ://이 붙는 웹 주소 중 // 뒤의 주소가 localhost로 시작하거나 문자 한 개 이상, 점, 문자 두 개 이상으로 구성된 웹 주소(예: https://lingo.dev/docs), 영문자와 숫자로만 이루어져 있으며 대문자·소문자·숫자가 각각 하나 이상 포함된 22자 식별자, 2024-01-15 또는 2024-01-15T10:00:00Z과 같은 ISO 8601 형식의 날짜 또는 날짜와 시간입니다. 원문은 해당 행의 모든 대상 로캘 셀에 기존 내용을 덮어쓰는 방식으로 입력되며, 해당 행은 번역을 위해 전송되지 않고 요금도 청구되지 않습니다. 1.5, 100%, 이메일 주소, 15.01.2024처럼 다른 형식으로 표기된 날짜 등 나머지 값은 번역됩니다. mailto: 및 tel: 링크, git+ssh://처럼 스킴에 다른 문자가 포함된 웹 주소, 주소가 localhost로 시작하지 않고 앞서 설명한 점도 없는 웹 주소(예: https://intranet 또는 https://a.b)도 번역됩니다.
대상 로캘의 열이 없으면 헤더 끝에 새 열을 추가합니다. 새 열이 여러 개라면 로캘 코드의 알파벳순으로 추가합니다. 그런 다음 모든 행의 셀 수가 같아지도록 빈 셀을 채워 표의 직사각형 구조를 유지합니다. 행 순서를 바꾸거나 행을 추가하거나 삭제하지는 않습니다.
오류 #
다음과 같은 경우에는 번역이나 요금 청구가 이루어지기 전에 파일 처리가 실패하며, 오류 메시지에 원인이 표시됩니다.
- 설정에 지정된
keyColumn가 헤더에 없거나, 첫 번째 헤더 셀이 비어 있고keyColumn도 설정되지 않은 경우 - 두 행의 키가 같아 번역이 잘못된 행에 들어가게 되는 경우
- 헤더에 원본 로캘의 열이 없는 경우
- 키 열이 대상 로캘의 열로도 사용되는 경우
- 헤더에 설정된
keyColumn, 원본 로캘 또는 대상 로캘의 이름이 두 번 이상 나오는 경우 - 행의 셀 수가 헤더의 셀 수보다 많은 경우
- 따옴표로 감싼 셀에 닫는 따옴표가 없는 경우
- 같은 셀의 닫는 따옴표 뒤에 텍스트가 오는 경우
파일을 수정한 뒤 다시 푸시하세요. CLI에서는 로캘마다 메시지를 반복하지 않고 파일 아래에 한 번만 표시합니다. 전체 실행이 실패하면 마지막 Run failed: 줄에 메시지가 다시 표시됩니다. GitHub App에서는 검사 실행에 메시지가 표시됩니다.
기존 번역 수정하기 #
문구를 원하는 대로 바꾸려면 셀을 직접 수정하세요. 번역 하나만 다시 생성하려면 해당 셀을 비우고 행의 나머지 부분은 그대로 둔 채 일반 푸시를 실행하세요.
lingo push --waitCLI --force는 애플 문자열 카탈로그에서와 마찬가지로 값이 있는 셀을 재사용합니다. --key로는 CSV 파일의 처리 범위를 좁힐 수 없습니다. CLI에서는 오류와 함께 푸시를 중단하고, GitHub App에서는 해당 파일을 건너뜁니다. CLI 정리는 원본과 출력 경로가 같으므로 해당 파일을 건너뜁니다. 커밋하기 전에 파일 전체의 변경 사항을 검토하세요.