키 제어

대부분의 경우 파일 안의 모든 문자열을 번역하게 됩니다. 하지만 브랜드명, 기능 플래그, 법률 문구, 내부용 잡다한 값처럼 예외가 필요할 때를 위해 CLI는 파일별로 세 가지 제어 기능을 제공합니다. 설정은 .lingo/config.json의 files[] 항목 안에서 합니다.

세 가지 모두 파일 구조를 그대로 따르는 점/대괄호 표기법 키 경로를 사용합니다:

{
  "files": [
    {
      "pattern": "content/en/app.json",
      "lockedKeys": ["meta.version"],
      "preservedKeys": ["legal.terms"],
      "ignoredKeys": ["internal.debug"]
    }
  ]
}

잠금 — 어디서나 동일한 값 유지#

lockedKeys는 원문 값을 번역하지 않고 모든 대상 파일에 복사합니다. 로캘 전반에서 바이트 단위까지 완전히 같아야 하는 값에 사용하세요:

{
  "pattern": "content/en/app.json",
  "lockedKeys": ["meta.version", "config.apiUrl"]
}

de.json와 fr.json는 정확한 원문 문자열로 meta.version됩니다. 원문이 바뀌면 다음 lingo push에서 새 값이 모든 로캘에 전파되며, 여전히 번역되지는 않습니다.

보존 — 직접 작성한 대상 값 보호#

preservedKeys는 이미 존재하는 대상 값을 엔진이 절대 덮어쓰지 않도록 합니다. 법률 문구, 규정 준수 카피, 또는 이미 검토를 마쳐 모델이 손대지 않게 하고 싶은 항목처럼 사람의 번역이 필요한 키에 사용하세요:

{
  "pattern": "content/en/settings.jsonc",
  "preservedKeys": ["featureFlags"]
}

엔진은 첫 번역 시 원문을 기준으로 해당 키를 채운 뒤, 그 이후 실행에서는 사용자가 수정한 내용을 그대로 유지합니다. 아래의 overrides와 비교해 보세요.

무시 — 출력에서 키 제외#

ignoredKeys는 대상 파일에서 해당 키를 완전히 제거합니다. 번역도 하지 않고, 복사도 하지 않으며, 기록도 하지 않습니다. 디버그 문자열, 내부 플래그, 테스트 데이터처럼 번역된 빌드에 절대 포함되면 안 되는 항목에 사용하세요:

{
  "pattern": "content/en/app.json",
  "ignoredKeys": ["internal.debug", "dev.testData"]
}

Overrides와 보존#

기존 대상 값이 실행 후에도 유지되는 방식은 두 가지입니다:

• 보존 (preservedKeys) — 선언적 방식입니다. 이 키는 설정에 의해 모든 로캘에서 영구적으로 보호됩니다.
• 로컬 수정 — lingo push는 각 대상의 해시를 lockfile과 비교합니다. 대상 파일을 직접 수정했다면 push는 이를 skipped (local edits)로 보고하고 그대로 둡니다. 덮어쓰려면 --force(범위와 함께)를 전달하세요. lingo push를 참고하세요.

보호가 영구적이고 모든 로캘에 걸쳐 적용돼야 한다면 preservedKeys를 사용하고, 일회성 수동 수정은 로컬 수정 감지에 맡기세요.

레거시 CLI에서 마이그레이션#

레거시 CLI에는 키 이름 변경(키 ID가 바뀌었을 때 기존 번역을 이어받는 기능)도 있었습니다. 하지만 이 기능은 현재 CLI에 포함되어 있지 않습니다. 번역 상태는 파일 해시별로 추적되므로 키 이름을 바꾸면 다음 push에서 다시 번역됩니다. 잠금, 보존, 무시는 모두 그대로 지원되지만 한 가지 차이가 있습니다. 경로는 예전의 슬래시 표기법(meta/version) 대신 점/대괄호 표기법(meta.version)을 사용합니다.