XML

어떤 XML 문서든 선언, 주석, 속성, 레이아웃을 바이트 단위까지 그대로 유지하면서 문서 내 텍스트를 번역합니다.

xml 파일 핸들러는 콘텐츠 내보내기 파일, 도움말 파일, 사용자 지정 리소스 형식 등 전용 형식으로 지원되지 않는 XML 문서의 텍스트를 번역합니다. 번역문을 원본 파일의 사본에 기록하므로 선언, 문서 형식 선언, 주석, 처리 명령, 속성, 네임스페이스, 공백은 그대로 유지됩니다. 번역된 텍스트와 직접 지정한 속성만 바뀝니다.

안드로이드 리소스, XLIFF, 애플 복수형 사전도 XML이지만, 각각 안드로이드, XLIFF, 애플 문자열 사전이라는 전용 형식이 있습니다. 이러한 파일에는 키, 복수형, 각 번역의 상태를 인식하는 전용 형식을 사용하세요.

XML 번역 설정 #

파일은 해당 파일 항목에 "format": "xml"가 설정된 경우에만 일반 XML로 번역됩니다. .xml 확장자만으로는 형식이 선택되지 않습니다. 안드로이드 strings.xml도 같은 확장자를 사용하기 때문입니다. 형식이 지정되지 않은 항목의 .xml 파일은 CLI에서 메시지를 표시한 뒤 건너뛰며, GitHub App에서도 건너뜁니다:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "content/en/*.xml", "format": "xml" }]
}

이 설정은 content/en/guide.xml에 대해 content/de/guide.xml와 content/fr/guide.xml를 기록합니다. 대상 경로에는 출력 경로에 설명된 JSON과 동일한 규칙이 적용되며, 다른 레이아웃은 targetPath로 선언합니다. 파일은 패턴이 일치하는 첫 번째 항목에 속합니다. 따라서 안드로이드 리소스는 "format": "android"를 사용하는 별도 항목에 두고, XML 항목에는 해당 리소스와 일치하지 않는 패턴을 지정하세요. 같은 설정을 CLI와 GitHub App에서 모두 사용할 수 있습니다.

번역 대상 #

텍스트가 들어 있는 각 요소가 하나의 번역 단위가 됩니다. 다른 요소, 주석, 공백만 들어 있는 요소는 자체 번역 단위를 갖지 않으며, 대신 하위 요소를 읽습니다:

xml
<?xml version="1.0" encoding="UTF-8"?>
<help>
  <!-- shown on the settings page -->
  <topic id="sync">
    <title>Sync your files</title>
    <p>Click <b>Sync</b> to upload your <a href="/files">files</a> now.</p>
  </topic>
</help>

여기서 title와 p는 각각 별개의 번역 단위입니다. 주석, id, href는 번역을 위해 전송되지 않습니다.

  • 인라인 요소. 위의 p처럼 텍스트 안에 요소가 있으면 문장 전체가 하나의 번역 단위가 됩니다. 인라인 요소는 모델이 위치를 옮길 수는 있지만 내용을 바꿀 수는 없는 플레이스홀더로 전달됩니다. 따라서 번역문에서는 대상 언어에 맞는 위치에 Sync와 files를 배치할 수 있습니다. 이러한 텍스트 안의 주석과 처리 명령도 같은 방식으로 보존됩니다.
  • 공백. 요소 사이의 들여쓰기처럼 공백으로만 이루어진 텍스트는 전송되지 않습니다. 텍스트 앞뒤의 공백은 파일에 그대로 남고, 텍스트 내부의 공백은 변경 없이 전송됩니다. 번역 과정에서 텍스트 앞뒤에 추가된 공백은 제거됩니다.
  • 문자 데이터 구역. 하나의 문자 데이터 구역으로만 이루어진 텍스트는 번역 후에도 문자 데이터 구역으로 기록됩니다. 다른 텍스트와 나란히 있는 문자 데이터 구역은 해당 텍스트의 일부로 취급되어 이스케이프 처리된 상태로 기록되지만, XML에서는 동일하게 읽힙니다.
  • 참조. &amp;, &lt;, &gt;, &quot;, &apos;와 &#169; 같은 문자 참조는 번역 전에 디코딩됩니다. &brand; 또는 &product-name;처럼 문서 형식 선언에 정의된 엔터티는 플레이스홀더처럼 보호되며 원래 모습 그대로 기록됩니다.
  • 일반 문장이 아닌 값. 숫자만으로 이루어진 텍스트, URL, ISO 날짜, 영문자와 숫자로 이루어진 22자 식별자는 번역하지 않고 모든 대상에 그대로 복사합니다.

요소 이름과 경로는 대소문자와 네임스페이스 접두사까지 작성된 그대로 읽습니다.

속성 번역 #

속성값은 translateComponentProps에 지정된 경우에만 번역됩니다. 문자열로 지정하면 모든 요소의 해당 속성을 번역하고, component가 있는 객체로 지정하면 지정된 요소의 해당 속성만 번역합니다:

json
{
  "pattern": "content/en/*.xml",
  "format": "xml",
  "translateComponentProps": ["title", { "component": "item", "props": ["label"] }]
}

이 설정은 모든 title 속성과 <item> 요소의 label 속성을 번역합니다. 이름은 작성된 그대로 정확히 일치해야 하므로 x:title와 Title는 서로 다른 속성으로 취급됩니다. 빈 값은 건너뜁니다. 식별자, 링크, xml:lang, 네임스페이스 선언은 직접 지정한 경우에만 번역됩니다. 따라서 실수로 지정하면 파일을 읽는 방식이 달라집니다.

번역문 기록 방식 #

번역된 텍스트에서는 &, <, >가 이스케이프 처리됩니다. 번역된 속성에서는 &, <, 해당 속성값을 감싸는 따옴표 문자가 이스케이프 처리됩니다. 탭과 줄바꿈은 XML에서 그대로 유지되도록 문자 참조로 기록합니다. 번역된 문자 데이터 구역에 ]]>가 있으면 두 구역으로 나누어 기록합니다. 번역문의 줄바꿈에는 해당 파일의 줄바꿈 형식을 사용합니다. XML에 포함할 수 없는 제어 문자는 번역문에서 제거됩니다.

선언에 encoding="ISO-8859-1"처럼 UTF-8이 아닌 인코딩이 지정되어 있으면, 번역문에서 ASCII 범위를 벗어나는 문자는 문자 참조로 기록합니다. 예를 들어 é는 &#xE9;로 기록하여 해당 인코딩에서도 대상 파일을 읽을 수 있게 합니다. 파일 자체는 UTF-8로 읽습니다. 따라서 다른 인코딩을 선언하고 악센트가 있는 문자를 원시 바이트로 포함한 파일은 해당 문자가 처음 나타나는 위치를 표시하며 처리가 실패하고, 아무것도 기록되지 않습니다. 파일을 UTF-8로 저장하거나 해당 문자를 문자 참조로 작성하세요.

핸들러는 xml:lang를 비롯해 문서의 언어를 나타내는 속성을 변경하지 않습니다. 빌드 과정에서 갱신하거나, 텍스트가 들어 있는 속성이라면 translateComponentProps에 지정하세요.

키와 번역 재사용 #

각 번역 단위는 XPath와 같은 방식으로 작성된 요소 경로를 키로 사용합니다. 예를 들면 /help/topic/title, /list/item[2], 속성의 경우 /menu/item[1]/@label와 같은 형태입니다. 위치는 이름이 같은 형제 요소가 있을 때만 표시됩니다. 이 키는 작업과 Studio에서 번역 단위를 식별하는 데 쓰입니다.

단위의 텍스트와 요소 경로(위치 제외)가 마지막 푸시 이후 바뀌지 않았고, 번역문이 원문의 인라인 요소와 중첩 구조를 그대로 유지하면 기존 번역이 유지됩니다. 대상 언어의 어순에 맞춰야 하는 경우가 많으므로 번역문에서 인라인 요소의 순서는 달라질 수 있습니다. 인라인 요소의 번역된 속성은 해당 요소와 함께 이동합니다. 요소를 삽입하면 새 요소만 번역되며, 그 뒤의 요소들은 위치가 바뀌어도 기존 번역을 유지합니다. 누군가 번역문에서 인라인 요소를 삭제하거나 다른 요소 안으로 옮기는 등의 이유로 번역문의 인라인 요소가 더 이상 원문과 일치하지 않으면 해당 번역문을 다시 번역합니다.

적용되지 않는 옵션 #

XML에는 키 규칙이 없습니다. CLI와 GitHub App은 lockedKeys, preservedKeys, ignoredKeys, keyColumn, injectLocale, translateFrontmatterFields 중 하나라도 설정된 XML 항목을 거부합니다. 허용하면 해당 옵션을 설정하지 않은 것처럼 파일이 번역되기 때문입니다. lockedPatterns도 자바 속성 파일을 제외한 다른 모든 형식에서와 마찬가지로 거부됩니다.

lingo push --key는 메시지를 표시한 뒤 XML 파일을 건너뛰고, 선택된 나머지 파일을 푸시합니다.

유효하지 않은 XML #

닫히지 않거나 짝이 맞지 않는 태그, 이스케이프 처리되지 않은 &, 두 개의 루트 요소, 루트 요소 바깥의 텍스트 등으로 XML 구문이 올바르지 않으면 첫 번째 문제가 있는 행과 열을 표시하며 파일 처리가 실패합니다. 파일 끝까지 닫히지 않은 태그가 여러 개 있으면 오류 메시지에 해당 태그 이름이 대신 표시됩니다. 요소의 중첩 깊이가 256을 넘는 파일도 처리에 실패합니다. 해당 파일에는 아무것도 기록되지 않으며, 기존 대상 파일은 그대로 유지됩니다. 대상 파일의 XML 구문이 올바르지 않아도 같은 방식으로 실패하며, 해당 로캘이 함께 표시됩니다. XML을 수정한 뒤 다시 푸시하세요.