문서 번역

원본 파일과 이전 번역을 업로드하고 현지화 작업을 시작한 뒤 결과 파일을 다운로드하세요.

문서 작업으로 파일 형식을 유지하면서 번역하세요. 하나의 작업에 여러 파일과 대상 언어를 포함할 수 있습니다. API는 각 파일의 바이트를 그대로 사용해 계산한 SHA-256 해시로 파일을 식별합니다.

API 키, 조직 식별자, 엔진 식별자가 필요합니다. 파일 현지화 가이드에서 노드제이에스로 작성된 전체 예제를 확인하세요.

형식 선택 #

각 문서에 format.type을 설정하세요.

형식유형
JSON / JSONCjson / jsonc
마크다운 / MDX / 마크독md / mdx / markdoc
HTMLhtml
타입스크립트 / PHPtypescript / php
YAML / 로캘 루트 YAML / OpenAPI YAMLyaml / yaml-root-key / yaml-openapi
안드로이드 / Flutter ARBandroid / flutter
애플 문자열 / 복수형 사전 / 문자열 카탈로그xcode-strings / xcode-stringsdict / xcode-xcstrings
겟텍스트 / XLIFF / 서브립po / xliff / srt
일반 텍스트txt
로캘별 열이 있는 CSV 표csv
자바 프로퍼티properties
Payload 콘텐츠payload

형식 레퍼런스에서 파일 구조와 제어 방식을 설명합니다. API의 format.options은 문서 규약을 사용하며, CLI 설정에서는 자체 옵션 이름을 이 규약에 맞게 변환합니다. 예를 들어 API는 마크다운에 frontmatterFields을, 컴포넌트 속성에 componentProps을 사용합니다. JSON 키 선택자는 제이슨패스를 사용합니다.

형식 옵션 설정 #

format.options을 생략하면 기본값이 적용됩니다. 선택한 유형에서 지원하는 옵션만 설정하세요.

유형옵션
json, jsoncJSON 옵션: 키 규칙, 범위, 컨텍스트, 힌트, 로캘 주입.
typescript, php, yaml, yaml-root-keylockedKeys, preservedKeys, ignoredKeys (기본값 []); keyScope 및 termScope은 선택 사항이며, 지정할 경우 비어 있으면 안 됩니다.
mdfrontmatterFields (기본값 ["$.title", "$.description"]); termScope은 선택 사항이며, 지정할 경우 비어 있으면 안 됩니다.
mdx, markdoc마크다운 옵션에 componentProps (기본값 []) 추가.
html핸들러에 기본 제공되는 번역 가능 속성 외에 componentProps (기본값 []) 추가.
xcode-stringsdictlockedKeys 및 preservedKeys (기본값 []); termScope은 선택 사항이며, 지정할 경우 비어 있으면 안 됩니다.
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapitermScope은 선택 사항이며, 지정할 경우 비어 있으면 안 됩니다.
csv키 열의 헤더를 지정하는 선택 사항 keyColumn (기본값: 첫 번째 헤더 셀).
propertieslockedKeys, preservedKeys, ignoredKeys(기본값 []) 및 keyScope(선택 사항, 빈 값 불가)는 키 전체를 대상으로 기존 방식의 패턴과 일치하는지 확인합니다. 단, 패턴이 $(으)로 시작하면 제이슨패스로 처리합니다. termScope도 선택 사항이며, 지정할 경우 빈 값은 허용되지 않습니다. lockedPatterns(기본값 [])은 값에서 번역하지 않고 유지할 부분을 지정하는 RE2 정규 표현식입니다.
payload, po, xliff, srt, txt추가 옵션이 없습니다.

키 규칙, 키 범위, 프런트 매터 필드는 제이슨패스 쿼리를 사용합니다. termScope은 지정한 용어 중 하나라도 부분 문자열로 포함하는 원본 단위 전체를 선택하며, 대소문자를 구분합니다. "cat"은 "catalog"과 일치할 수 있습니다. 형식이 keyScope과 termScope을 모두 지원할 때 둘 다 지정하면 두 범위의 교집합이 선택됩니다. 어느 범위를 사용하든 병합할 기존 번역이 필요합니다. 선택과 재사용 방식은 증분 업데이트에서 설명하듯 형식에 따라 달라집니다. 이러한 API 옵션은 CLI의 --key 형식 지원과 다릅니다.

컴포넌트 속성 규칙에는 속성 이름을 담은 비어 있지 않은 배열인 props이 포함됩니다. 선택 사항인 components은 규칙 적용 대상을 이름이 지정된 컴포넌트로 제한하는 비어 있지 않은 배열입니다. components을 생략하면 모든 컴포넌트에 규칙이 적용됩니다. MDX의 경우:

json
{
  "type": "mdx",
  "options": {
    "frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
    "componentProps": [{ "components": ["Callout"], "props": ["title"] }]
  }
}

이렇게 하면 문서 본문과 함께 선택한 프런트 매터와 리터럴 Callout 제목이 번역됩니다. 코드와 표현식의 보호 방식 및 재구성 동작은 형식 레퍼런스에서 확인하세요.

아티팩트 주소로 작업 생성 #

업로드할 바이트를 그대로 사용해 해시를 계산하세요. 노드제이에스의 경우:

js
import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";

const bytes = await readFile("messages/en.json");
const address = createHash("sha256").update(bytes).digest("hex");

계산한 주소를 문서의 source으로 지정해 작업을 생성하세요.

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "documents": [
    {
      "key": "messages/en.json",
      "format": { "type": "json" },
      "source": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}

예제 주소를 계산한 해시로 바꾸고, 반환된 작업 식별자를 저장하세요. uploads에는 저장소에 없는 입력 아티팩트가 나열됩니다. 이미 저장된 콘텐츠는 다시 업로드할 필요가 없습니다.

바이트 업로드 및 작업 시작 #

각 uploads 항목에 대해 인증된 PUT 요청을 해당 uploadUrl으로 보내세요. 이때 Content-Type: application/octet-stream을 포함하고 원본 바이트를 요청 본문으로 사용하세요. 작업을 시작하기 전에 원본 파일과 참조된 이전 파일을 모두 업로드하세요.

아티팩트의 최대 크기는 파일당 25 MiB입니다. 해시가 일치하지 않으면 ArtifactChecksumMismatch이, 파일 크기가 제한을 초과하면 RequestBodyTooLarge이 반환됩니다. 텍스트의 해시를 계산한 뒤 업로드 전에 줄바꿈 형식을 바꾸면 바이트가 달라져 검증에 실패합니다.

모든 업로드가 성공하면 POST /v2/localization/jobs/:id/start을 호출하세요. 아티팩트는 작업이 시작되기 전에만 업로드할 수 있습니다. 작업의 대상별 진행 상황을 확인한 다음, 반환된 URL에서 완료된 파일을 다운로드하세요.

기존 문서 업데이트 #

증분 업데이트를 위해 새 원본, 이전 원본, 각 대상 로캘의 현재 번역을 보관하세요. 다음 세 가지 입력을 제공해야 합니다.

  • source: 새 원본의 아티팩트 주소.
  • previousSource: 이전 리비전에 사용한 원본 주소.
  • previousTranslations: 사용 가능한 번역마다 하나씩 지정하는 { "locale": "de", "artifact": "..." } 항목.

이전 대상 파일의 바이트를 제공할 때는 로컬에서 사람이 수정한 내용도 포함하세요. 형식 핸들러는 변경되지 않은 콘텐츠를 재사용하고 변경된 콘텐츠를 번역할 수 있습니다. 일반 JSON에서는 이전 원본을 생략하면 원본이 변경되지 않은 콘텐츠를 재사용할 수 없습니다. 다른 형식은 자체 병합 규칙에 따라 기존 대상 콘텐츠를 반영할 수 있습니다. 원본이 수정된 메시지와 변경되지 않은 메시지를 구분해야 한다면 전체 기준본을 보관하세요.

keyScope 또는 termScope으로 범위를 지정해 요청하려면 모든 대상 로캘에 이전 번역이 있어야 합니다. JSON, JSONC, 타입스크립트, PHP는 원본 값이 변경되지 않은 문자열까지 포함해 선택된 문자열을 다시 생성하고 기존 대상에 병합합니다. YAML, 로캘 루트 YAML, OpenAPI YAML은 이전 원본이 제공되면 선택된 콘텐츠 중 변경되지 않은 부분을 재사용할 수 있습니다. XCStrings는 이전 원본이 없어도 파일에 포함되어 있거나 별도로 제공된 대상 값을 재사용할 수 있습니다. 따라서 단위를 선택한다고 해서 항상 새로운 번역 작업이 발생하는 것은 아닙니다.

재생성을 요청하기 전에 원하는 용어나 규칙을 엔진에 제공하고, 생성된 대상 결과를 확인하세요. 정확히 원하는 문구로 수정하려면 대상을 직접 편집하세요. 그러면 특정 문구를 얻기 위해 재생성에 의존하지 않아도 됩니다.

후속 작업을 생성하기 전에 PUT /v2/organizations/:orgId/localization/artifacts/:address으로 인증된 요청을 보내 기준본을 저장하세요. 파일 바이트를 요청 본문으로 사용합니다. 이 경로를 사용하려면 조직 내 엔진에 대한 번역 권한이 필요하며, 요청 결과로 아티팩트 메타데이터가 반환됩니다. 동일한 25 MiB 제한과 해시 검사가 적용됩니다.

결과는 먼저 임시 파일로 다운로드하세요. 애플리케이션 파일을 교체하기 전에 결과를 제출한 원본 리비전 및 제출 이후 대상에 적용된 수정 사항과 비교하세요. 관련 CLI 워크플로는 검토된 번역 보존에서 확인할 수 있습니다.