자바 프로퍼티
주석과 빈 줄, 각 줄의 배치를 그대로 유지하면서 자바 .properties 리소스 번들을 키별로 번역합니다.
.properties 파일은 한 줄에 하나씩 키와 메시지를 연결하며, 자바의 ResourceBundle과 스프링의 MessageSource이 이 형식으로 파일을 읽습니다. properties 파일 처리기는 각 키의 값을 번역해 원본 파일의 사본에 기록합니다. 주석, 빈 줄, 키 순서, 구분자, 공백은 그대로 유지되고, 번역된 키의 값만 바뀝니다.
프로퍼티 번역 설정 #
프로퍼티 파일은 패턴이 .properties으로 끝나 형식이 자동으로 추론되거나 "format": "properties"을 설정한 파일 항목에서만 선택됩니다. "format": "properties"을 지정한 항목은 .properties 파일만 선택합니다. 해당 형식을 지정하지 않으면 src/main/resources/**/*처럼 범위가 넓은 패턴도 프로퍼티 파일을 선택하지 않으므로, application.properties 같은 설정 파일이 실수로 번역되는 일을 막을 수 있습니다.
messages_en.properties처럼 파일 이름에 로캘이 포함되어 있으면, 각 대상 파일은 파일 이름의 같은 자리에 대상 로캘을 넣어 원본 파일 옆에 생성됩니다. 로캘은 밑줄을 쓰는 자바 형식인 pt_BR으로 표기하며, ResourceBundle이 이 형식으로 로캘을 찾습니다:
{
"sourceLocale": "en",
"targetLocales": ["de", "pt-BR"],
"files": [{ "pattern": "src/main/resources/messages_en.properties" }]
}이 설정으로 messages_de.properties과 messages_pt_BR.properties가 생성됩니다. 지역이 포함된 원본 로캘도 같은 방식으로 찾습니다. "sourceLocale": "en-US"인 경우 원본은 messages_en_US.properties입니다. pt-BR에 대해 "bcp47" 같은 다른 형식을 사용하려면 항목에 localeFormat을 설정하세요. 원본이 이름에 로캘이 없는 기본 번들인 messages.properties이면 대상 경로를 명시하세요:
{
"pattern": "src/main/resources/messages.properties",
"targetPath": "src/main/resources/messages_[locale].properties"
}같은 설정을 CLI 및 GitHub App에서 사용할 수 있습니다.
파일을 읽는 방식 #
키와 값은 java.util.Properties과 같은 방식으로 읽습니다:
- 단위. 키 하나가 번역 단위 하나입니다. 같은 키가 두 번 나오면 자바가 읽는 마지막 값을 한 번만 번역합니다. 해당 키가 나오는 모든 위치에 이 번역을 기록합니다.
- 구분자.
=,:또는 공백 문자로 키와 값을 구분합니다.=과:앞뒤에는 공백을 넣을 수 있습니다. - 주석과 빈 줄. 공백을 제외한 첫 문자가
#또는!인 줄은 주석입니다. 주석과 빈 줄은 번역 대상으로 전송하지 않습니다. - 줄 이어쓰기.
\으로 끝나는 줄은 다음 줄로 이어지며, 다음 줄의 맨 앞 공백은 제거됩니다. 여러 줄에 걸친 값은 다시 기록할 때 한 줄로 합쳐집니다. - 이스케이프.
\uXXXX,\t,\n,\r,\f,\=,\:,\,\\및 그 밖의 모든 이스케이프 문자는 번역 전에 디코딩됩니다. 잘못된\u이스케이프가 있으면 자바에서와 마찬가지로 파일 처리가 실패합니다. - 빈 값. 값이 비어 있거나 공백만 있는 키는 번역하지 않고 그대로 둡니다. 대상 파일의 빈 값은 미번역으로 간주하지만,
preservedKeys에 있는 키는 예외로 빈 값을 유지합니다.
파일은 UTF-8로 읽습니다. 악센트 문자가 원시 바이트로 저장된 ISO-8859-1 파일은 지원하지 않습니다. UTF-8로 저장하거나 해당 문자를 \uXXXX 형식으로 작성하세요. 파일 시작 부분의 UTF-8 바이트 순서 표식은 유지되지 않습니다.
번역을 기록하는 방식 #
자바가 번역된 값을 그대로 다시 읽을 수 있도록 각 값에 이스케이프를 적용합니다. 역슬래시, 줄 바꿈, 탭, 폼 피드와 그 밖의 제어 문자, 값 맨 앞의 공백, = 또는 :이 이스케이프 대상입니다. 아스키 범위 밖의 문자는 파일에 이미 있는 값의 표기 방식에 맞춰 기록하며, 주석은 판단 기준에서 제외합니다:
| 대상 파일의 값 상태(첫 대상 파일이 생성되기 전에는 원본의 값 상태) | é 또는 中 같은 문자의 기록 방식 |
|---|---|
| 원시 UTF-8 텍스트가 이미 있음 | 그대로 기록 |
| 아스키 문자만 있음 | \u00E9, \u4E2D 형식으로 기록 |
값을 이스케이프하는 경우에는 기록하는 모든 값에 이스케이프를 적용합니다. 원본에 원시 텍스트로 들어 있는 잠금 값이나 보존된 값도 포함됩니다. 이스케이프가 적용된 파일은 UTF-8 리더와 ISO-8859-1로 읽는 Properties.load(InputStream) 모두에서 불러올 수 있습니다.
{0}, {name}, %s 같은 자리표시자는 번역에서도 그대로 유지됩니다. 인수가 있는 메시지에서 아포스트로피를 ''로 쓰는 것과 같은 자바 MessageFormat 인용 규칙은 자동으로 적용되지 않습니다.
키와 텍스트를 번역하지 않고 유지하기 #
lockedKeys, preservedKeys, ignoredKeys은 이전 CLI와 마찬가지로 키 전체를 기준으로 일치 여부를 판단합니다. 패턴과 동일한 키, 패턴 뒤에 ., / 또는 -이 붙어 이어지는 키, 글로브 패턴에 맞는 키가 일치 대상입니다. 따라서 app은 app.title과, app.*은 app.title 및 app.menu.save과, *.port는 server.port과 일치합니다. 단, $로 시작하는 패턴은 $["app.title"]처럼 키를 대상으로 하는 JSONPath 쿼리로 처리됩니다.
| 옵션 | 대상 파일에 반영되는 결과 |
|---|---|
lockedKeys | 원본 값을 사용하며, 번역 대상으로 전송하지 않습니다. |
preservedKeys | 대상 파일의 기존 값을 사용하며, 기존 값이 없으면 원본 값을 사용합니다. |
ignoredKeys | 이어지는 줄까지 포함해 항목 전체를 제외합니다. |
lockedPatterns은 값의 일부를 번역하지 않고 유지합니다. 각 항목은 RE2 문법으로 작성한 정규 표현식이며, 각 값에서 일치하는 모든 부분이 잠깁니다. ^과 $는 값 내부의 줄 바꿈 위치에 일치합니다:
{
"pattern": "src/main/resources/messages_en.properties",
"lockedPatterns": ["\\{\\{[^}]+\\}\\}"]
}일치한 부분은 반드시 유지해야 하는 토큰으로 모델에 전송되고, 바이트 단위까지 그대로 다시 기록됩니다. 일치한 부분을 누락하거나 변경한 번역은 거부되며 기록되지 않습니다. 패턴은 각 값 안에서만 일치하며, 여러 줄이나 키, 주석에 걸쳐 일치하지 않습니다. 일치하는 부분이 있는 값에서는 {0}과 %s 같은 자리표시자도 같은 방식으로 보호됩니다.
RE2는 텍스트 길이에 비례하는 시간 안에 실행되므로 전후방 탐색((?=, (?!, (?<=, (?<!)과 역참조(\1, \k<name>)를 지원하지 않습니다. 아스키 범위 밖의 문자는 \u00E9이 아닌 \x{00E9} 형식으로 작성하세요. CLI 및 GitHub App은 설정을 읽을 때 정규 표현식이 아닌 패턴을 거부합니다. RE2가 지원하지 않는 문법을 사용하면 해당 패턴의 이름을 표시하며 푸시가 실패합니다. lockedPatterns은 프로퍼티 파일에만 적용되며, 다른 형식의 항목에 설정하면 해당 항목이 거부됩니다.
--key은 lockedKeys와 같은 일치 방식을 사용해 푸시 대상을 지정한 키로 한정합니다.
재사용 및 수정 #
마지막 푸시 이후 원본 값이 바뀌지 않은 키는 기존 번역을 유지합니다. 원본 값이 바뀌면 해당 키를 다시 번역합니다. 대상 파일에만 있는 키는 제거되며, 대상 파일의 키는 원본의 순서와 배치를 따릅니다.
--key을 사용해 푸시하면 기존 대상 파일을 수정하는 방식으로 동작합니다. 선택한 값만 바뀌고, 대상 파일에만 있는 키와 주석을 비롯한 나머지 줄은 그대로 유지됩니다. 선택한 키가 대상 파일에 없으면 파일 끝에 추가됩니다.
번역 하나를 수정하려면 대상 파일에서 직접 편집하세요. 번역을 다시 생성하려면 --key을 사용해 다시 푸시하세요:
lingo push --key checkout.title --wait