CLI 설정

.lingo/config.json에서 소스 검색, 번역 옵션, 대상 경로를 정의하세요.

.lingo/config.json는 프로젝트에서 번역할 파일과 번역 결과를 저장할 위치를 정의합니다. CLI는 작업 디렉터리에서 상위 디렉터리로 올라가며 가장 가까운 설정 파일을 찾고, 그 루트를 기준으로 프로젝트 상대 경로를 해석합니다. 설정 파일이 없으면 로컬 카탈로그 명령은 현재 작업 디렉터리를 사용합니다.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "locales/en.json" }]
}

link를 실행해 원격 번역에 필요한 조직 및 로컬라이제이션 엔진 식별자를 추가하세요. 추출 작업은 이 식별자 없이도 로컬에서 i18n 설정을 사용할 수 있습니다. 엄격한 JSON 문법을 따라야 하며, 주석과 후행 쉼표는 허용되지 않습니다.

루트 필드 #

필드의미
orgId, engineId비어 있지 않은 리소스 식별자입니다. 두 식별자가 함께 원격 연결을 구성합니다.
sourceLocale비어 있지 않은 소스 로캘 문자열입니다.
targetLocales비어 있지 않은 문자열 항목입니다. 실행 시 중복 항목과 소스 로캘에 정확히 일치하는 항목을 제거합니다.
files아래에서 설명하는 소스 항목입니다.
i18n.messagesPath추출·검사·정리에 사용할 카탈로그 디렉터리입니다. 기본값은 locales입니다.
i18n.typesPath추출·검사에 사용할 선언 파일 경로입니다. 기본값은 lingo.d.ts입니다.
github.workflows.onPushToDefaultBranch.enabled기본 브랜치 통합 트리거입니다. 선택 사항입니다.
github.workflows.onPullRequest.enabled풀 리퀘스트 통합 트리거입니다. 선택 사항입니다.
github.safety.requireApproval통합 실행 승인 설정입니다. 선택 사항입니다.

알 수 없는 루트 키와 파일 항목 키는 경고를 표시한 뒤 무시됩니다. 오타가 있어도 파일 전체가 거부되는 대신 기본값이 그대로 적용될 수 있습니다.

초기화 명령은 로컬라이제이션 설정을, 연결 명령은 연결 식별자를 기록합니다. 연결 해제 명령은 해당 식별자만 제거합니다. 이 명령들은 다른 루트 섹션을 보존하지만, init --force는 파일 항목을 다시 구성하므로 고급 옵션이 사라집니다. GitHub 설정만으로는 앱이 설치되지 않으며, CLI 푸시가 저장소 자동화를 실행하도록 설정되지도 않습니다. 통합 설정을 이용하세요.

파일 항목 필드 #

필드의미
pattern비어 있지 않은 소스 패턴 하나입니다.
include소스 패턴 목록입니다. 비어 있어도 pattern보다 우선합니다.
exclude이 항목에서 제외할 패턴입니다.
format아래 지원 목록에서 명시적으로 지정하는 형식입니다.
localeFormatbcp47, underscore 또는 android 경로 표기 방식입니다.
targetPath, sourceRoot출력 템플릿과 [path]에서 제거할 접두사입니다. 접두사는 선택 사항입니다.
translateFrontmatterFields마크다운 계열 처리기가 선택하는 메타데이터 필드입니다.
translateComponentProps속성 이름 또는 컴포넌트별로 필터링한 속성 규칙입니다.
lockedKeys, preservedKeys, ignoredKeys해당 기능을 지원하는 처리기에서 사용하는 비어 있지 않은 키 경로 배열입니다.
injectLocale불리언 또는 { "enabled": true, "key": "language" }입니다.
keyColumnCSV 전용 키 열 헤더입니다. 기본값은 첫 번째 헤더 셀입니다.
lockedPatterns프로퍼티 형식에만 해당: 값에 포함된 RE2 정규식은 번역하지 않고 그대로 유지합니다.

각 항목에는 pattern 또는 include가 필요합니다. include가 비어 있으면 아무것도 선택하지 않습니다. 처음 일치하는 항목의 옵션이 적용됩니다. 값의 소유권과 형식별 경계는 키 제어에서 설명합니다.

파일 패턴 #

패턴 일치 기능은 경로 구간 안에서 *를, 여러 디렉터리에 걸쳐서는 **/를 지원합니다. 하위 트리를 재귀적으로 지정하려면 docs/en/**/*를 사용하세요. 끝에 **만 붙이는 것은 같은 의미가 아닙니다. 다른 글로브 라이브러리의 중괄호나 확장 글로브 동작이 그대로 적용된다고 가정하지 마세요.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "files": [
    {
      "include": ["docs/en/**/*.md", "docs/en/**/*.mdx"],
      "exclude": ["docs/en/private/**/*"]
    }
  ]
}

제외 규칙은 해당 항목에만 적용되므로 다른 항목에서는 같은 파일을 포함할 수 있습니다. 파일 검색은 .git와 node_modules를 건너뛰지만, .gitignore에 있는 모든 항목을 건너뛰지는 않습니다. 위치 인수로 지정한 푸시 패턴은 설정된 소스와 겹치는 범위로 대상을 더 좁히고 계획 모드를 변경합니다. 셸에서는 이 패턴을 따옴표로 감싸세요.

형식 선택 #

설정된 형식은 json, jsonc, md, mdx, markdoc, yaml-openapi, po, flutter, xcode-strings, yaml, android, typescript, xcode-xcstrings, srt, xliff, xcode-stringsdict, php, yaml-root-key, html, txt, csv, properties입니다.

접미사추론되는 형식
.json, .jsoncJSON 또는 JSONC.
.md, .mdx, .mdoc마크다운, MDX, 마크독.
.html, .htmHTML.
.po, .arb겟텍스트, Flutter.
.strings, .xcstrings, .stringsdict해당 애플 형식.
.ts, .mts, .cts타입스크립트.
.srt, .xlf, .xliff, .php서브립, XLIFF, PHP.
.txt일반 텍스트. 패턴이 .txt로 끝나거나 형식이 txt인 경우에만 해당합니다.
.csvCSV. 패턴이 .csv로 끝나거나 형식이 csv인 경우에만 해당합니다.
.properties자바 프로퍼티 형식이며, 패턴이 .properties 또는 properties 형식으로 끝나는 경우에만 해당합니다.
.yaml, .ymlyaml, yaml-root-key 또는 yaml 기반 오픈 API를 명시적으로 설정하세요.
.xmlandroid를 명시적으로 설정하세요. 일반 XML은 지원하지 않습니다.

OpenAPI의 정확한 식별자는 yaml-openapi입니다. 형식을 명시적으로 선택해도 파일 탐색에서 지원하는 확장자 목록의 제한은 그대로 적용됩니다. .txt, .csv, .properties 파일은 패턴이 해당 확장자로 끝나거나 그에 맞는 형식인 txt, csv, properties을 설정한 항목에만 속합니다. 이러한 항목은 해당 확장자의 파일만 선택합니다. .js, .tsx, .pot, MJML, VTT 파일은 CLI 파일 입력으로 설정되어 있지 않습니다. 리액트 TSX 추출은 별개의 작업입니다.

HTML 번역은 선택한 텍스트와 속성을 원본 소스에 반영하고, 나머지 마크업과 주석, 서식은 그대로 보존합니다. 명시적인 <html> 요소가 있으면 해당 요소의 lang 속성에 대상 로캘을 넣습니다. 문서 조각은 조각 상태로 유지됩니다. 텍스트 선택과 출력 동작은 HTML을 참고하세요.

형식에서는 건너뛰는 구조와 재구성의 한계를 비롯한 파서 동작을 설명합니다. 공유 서버 처리기가 있다고 해서 이 CLI에서 선택할 수 있는 형식이 늘어나는 것은 아닙니다.

출력 경로 #

소스 경로만으로 로캘을 식별할 수 없다면 템플릿을 명시적으로 지정하세요:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    {
      "pattern": "docs/**/*.md",
      "sourceRoot": "docs",
      "targetPath": "i18n/[locale]/docs/[path]"
    }
  ]
}

docs/start.md는 i18n/de/docs/start.md와 i18n/fr/docs/start.md가 됩니다. [locale]는 해당 항목의 로캘 표기 방식을 사용하고, [path]는 경로 구간 경계에 맞춰 소스 루트를 제거합니다. 루트가 docs이면 docsite의 일부를 제거하지 않습니다.

템플릿에는 [locale]가 필요하며, 글로브 입력에는 [path]도 필요합니다. 사용할 수 있는 자리표시자는 이 둘뿐입니다. 절대 경로, .., 글로브 루트, 입력 범위 밖의 루트, 설정된 소스로 다시 검색되는 출력은 허용되지 않습니다. targetPath 없이 sourceRoot를 사용할 수는 없습니다. 푸시는 대소문자를 구분하지 않고 출력 경로 충돌도 검사합니다.

푸시, 풀, 완전 삭제 작업도 파일시스템의 실제 경로를 따릅니다. 소스, 대상, .lingo/lock.json 또는 .lingo/config.json가 심볼릭 링크 등을 통해 프로젝트 루트 밖이나 .git 안으로 연결되면, 해당 위치에서 읽기·쓰기·삭제를 수행하기 전에 오류와 함께 명령이 중단됩니다. 프로젝트 내부로 연결되는 링크는 계속 사용할 수 있지만, 대상이나 Lockfile 자체가 링크이면 그 링크를 통해 쓰지 않습니다. 모노레포에서는 패키지에서 공유 파일로 링크를 만드는 대신, 공유 파일이 포함된 루트에서 실행하세요.

템플릿이 없으면 소스 로캘 디렉터리, 확장자를 제외한 파일명 전체, 플랫폼별 구조 순서로 경로 도출을 시도합니다. 마지막 수단으로는 경고를 표시하고 로캘 디렉터리를 삽입합니다. 예를 들어 locales/en.json → locales/de.json, app_en.arb → app_de.arb, Base.lproj → 대상 .lproj, 안드로이드 values → 로캘 한정 리소스로 처리됩니다. 경고를 읽고 애플리케이션이 해당 위치에서 파일을 불러오는지 확인하세요.

엑스시스트링스와 CSV는 모든 로캘을 소스 파일에 저장하며 targetPath를 허용하지 않습니다. 여러 로캘의 출력이 의도적으로 같은 파일을 공유하므로, 파일이 존재한다고 해서 각 로캘이 모두 들어 있다는 뜻은 아닙니다. 완전 삭제는 공유 파일을 건너뛰므로 개별 로캘 항목을 제거할 수 없습니다.

메타데이터 및 컴포넌트 텍스트 선택 #

마크다운 계열 번역에서 옵션을 생략하면 프런트매터의 title와 description를 선택합니다. 빈 목록을 지정하면 선택하지 않고, 목록을 명시하면 다른 필드를 선택할 수 있습니다. 중첩된 스칼라 및 배열 경로를 사용하려면 프런트매터를 파싱할 수 있어야 합니다. 프런트매터 형식이 잘못되면 최상위 수준을 스캔하는 방식으로 대체될 수 있습니다.

json
{
  "pattern": "docs/en/**/*.mdx",
  "translateFrontmatterFields": ["title", "description"],
  "translateComponentProps": ["aria-label", { "component": ["Card", "Callout"], "props": ["title"] }]
}

문자열은 컴포넌트 필터 없이 속성을 선택합니다. 객체는 props를 선택하며 컴포넌트 이름으로 범위를 제한할 수 있습니다. 이 규칙이 선택하는 대상은 번역 가능한 리터럴 콘텐츠이지, 컴포넌트 코드나 모든 속성이 아닙니다. 마크다운, MDX, 마크독은 서로 다르므로 경로를 전환할 때는 처리기를 확인하세요.

JSONC에서 번역 지침을 제공하려면 해당 문자열 바로 앞에 @context를 배치하세요. 일반 JSONC 출력은 @orphan 표시를 유지하지만 다른 주석은 제거합니다. 따라서 리액트의 @src 메타데이터는 풀 작업에서 보존된다고 가정하지 말고 카탈로그 불러오기 정책에 따라 처리해야 합니다.

문서 프레임워크에서는 실제 소스 및 출력 디렉터리를 라우팅과 별도로 선택하세요. 오픈 API는 yaml-openapi, 레일스 스타일 로캘 루트는 yaml-root-key, 일반 YAML은 yaml를 사용합니다. 확장자가 일치하는 것만으로 올바른 처리 방식이 선택되지는 않습니다.

로캘 #

설정에서는 전체 로캘을 나열한 열거형과 대조하는 대신, 비어 있지 않은 문자열인지 검사합니다. 지역이나 문자 체계를 포함해 모델과 애플리케이션에 필요한 식별자를 사용하세요. localeFormat는 경로를 제어합니다. bcp47는 하이픈을 유지하고, underscore는 pt_BR를 생성하며, android는 pt-rBR 또는 b+zh+Hans 같은 형태를 생성합니다. 안드로이드 형식은 별도로 재정의하지 않는 한 안드로이드 표기 방식을 사용하며, 이는 소스 일치 여부에도 영향을 줍니다.

대상 로캘을 추가하고 누락된 파일을 채우기 전에, 처리하지 않은 일반 소스 업데이트를 먼저 마무리하세요. 언어 추가에서는 이 순서가 기존 언어를 최신 상태로 유지하는 데 어떻게 도움이 되는지 설명합니다. 대상 로캘을 제거하면 이후에는 선택되지 않지만 기존 파일은 삭제되지 않습니다. 파일에 포함된 로캘 메타데이터와 공유 카탈로그에는 해당 처리기의 규칙을 따라야 합니다. 경로를 올바르게 표기했다고 해서 쓰기 방향, 라우팅, 언어 품질까지 보장되지는 않습니다.

카탈로그 경로 #

추출 및 검사에서는 명시적으로 지정한 --out/--types가 가장 먼저 적용되고, 그다음으로 i18n 설정, 기본값 순으로 적용됩니다. --source-locale의 기본값은 로컬라이제이션 sourceLocale와 별개로 en입니다. messagesPath를 변경해도 files[]는 업데이트되지 않습니다. 번역 대상으로 생성된 JSONC 경로를 선택하세요.

모노레포 #

루트 설정을 사용하면 재귀적으로 탐색하거나 명시적으로 지정한 패키지 경로 전반에서 로캘과 로컬라이제이션 엔진을 공유할 수 있습니다. 반대로 패키지별 설정을 사용하면 로캘, 설정, Lockfile을 각각 독립적으로 유지할 수 있습니다. 가장 가까운 설정 파일을 찾는 과정에서 의도치 않게 상위 설정이 선택되지 않도록 원하는 패키지 루트에서 실행하세요.

지속적 통합의 디렉터리 매트릭스는 각 프로젝트에서 수집한 출력을 보존하고 쓰기 작업이 겹치지 않도록 구성해야 합니다. 홈 디렉터리에 로컬로 저장되는 실행 포인터는 절대 루트 경로에 의존하며 Lockfile을 통해 공유되지 않습니다. lingo check는 files가 선택한 모든 소스를 파일 단위로 Lockfile과 비교합니다. 파일 내부의 키는 검사하지 않습니다.

점수 평가 설정 #

lingo score는 지티를 통해 불러오는 실행 가능한 lingo.config.ts를 사용합니다. 이 설정은 프로젝트 JSON과 별개이며, 임의의 로컬 형식 로더를 등록하지 않습니다. 신뢰할 수 있는 점수 평가 플러그인과 원격 파일 로컬라이제이션 설정을 구분해 관리하세요.