키 보존 - Lingo.dev CLI

Lingo.dev CLI를 사용하면 특정 번역 키를 보존하여 한 번 초기화된 후 후속 CLI 작업에서 덮어쓰지 않도록 할 수 있습니다. 보존된 키는 소스에서 플레이스홀더로 복사된 후 자동 번역 업데이트로부터 보호됩니다.

키를 보존하면 CLI가 소스 값으로 초기화한 다음 향후 번역 실행 시 해당 키를 건너뜁니다.

키 보존 설정

i18n.json의 버킷 구성에 preservedKeys를 추가하세요:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "preservedKeys": ["legal/privacy", "legal/terms", "marketing/tagline"]
    }
  }
}

preservedKeys 배열은 슬래시(/) 표기법을 사용하여 중첩된 키를 지정하고 별표(*)를 사용하여 여러 키를 매칭합니다.

키 보존 작동 방식

번역 처리 중 Lingo.dev CLI는:

보존된 키 식별 — 구성에서 보존된 키를 찾습니다
번역에서 제외 — 보존된 키는 번역 엔진으로 전송되지 않습니다
누락된 키 초기화 — 새 대상 파일에 대한 플레이스홀더로 소스 값을 복사합니다
기존 값 보호 — 수동으로 번역된 콘텐츠를 변경하지 않고 유지합니다

예시 워크플로:

// locales/en.json (source)
{
  "welcome": "Welcome to our platform",
  "legal": {
    "privacy": "We respect your privacy and protect your data.",
    "terms": "By using this service, you agree to our terms."
  }
}

보존된 키 구성:

{
  "preservedKeys": ["legal/privacy", "legal/terms"]
}

생성된 스페인어 번역(첫 실행):

// locales/es.json (generated)
{
  "welcome": "Bienvenido a nuestra plataforma",
  "legal": {
    "privacy": "We respect your privacy and protect your data.",
    "terms": "By using this service, you agree to our terms."
  }
}

welcome 키는 번역됩니다. legal 섹션은 나중에 수동 번역을 위해 그대로 복사됩니다.

중첩된 키 경로

슬래시(/) 표기법을 사용하여 모든 깊이의 키를 보존하세요:

{
  "preservedKeys": [
    "legal/privacy/full",
    "legal/terms/conditions",
    "marketing/campaigns/holiday"
  ]
}

이 표기법은 복잡한 중첩 구조에서도 작동합니다:

// Source structure
{
  "legal": {
    "privacy": {
      "full": "Full privacy policy text..."
    }
  }
}

legal/privacy/full 경로는 이 특정 중첩 키를 보존합니다.

점이 포함된 키

슬래시 표기법은 이름에 점이 포함된 키를 처리합니다:

// Source with dotted key names
{
  "legal": {
    "privacy.policy": "Privacy policy content",
    "terms.of.service": "Terms of service content"
  }
}

다음을 사용하여 이러한 키를 보존합니다:

{
  "preservedKeys": ["legal/privacy.policy", "legal/terms.of.service"]
}

여러 버킷 유형

다양한 파일 형식은 서로 다른 보존 키를 가질 수 있습니다:

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "preservedKeys": ["legal/privacy", "legal/terms"]
    },
    "yaml": {
      "include": ["translations/[locale].yml"],
      "preservedKeys": ["compliance/gdpr", "compliance/ccpa"]
    }
  }
}

각 버킷 유형은 콘텐츠 구조에 따라 자체 보존 키 목록을 유지합니다.

키 보존 vs 키 잠금

키 보존과 키 잠금은 서로 다른 목적을 가지고 있습니다:

키 보존(preservedKeys):

키는 소스 값을 플레이스홀더로 사용하여 한 번 초기화됩니다
기존 타겟 값은 CLI에 의해 절대 덮어쓰이지 않습니다
수동 번역이나 법적 검토가 필요한 콘텐츠에 사용됩니다

키 잠금(lockedKeys):

키는 번역 처리에 포함되지만 값은 변경되지 않은 상태로 유지됩니다
잠긴 키는 항상 소스 값과 정확히 일치합니다
기술 식별자, 컴포넌트 이름 또는 일관성을 유지해야 하는 값에 사용됩니다

비교 예시:

// Source file
{
  "welcome": "Welcome",
  "system": {
    "component": "Lingo.dev Engine"
  },
  "legal": {
    "privacy": "Privacy policy text"
  }
}

// Configuration
{
  "lockedKeys": ["system/component"],
  "preservedKeys": ["legal/privacy"]
}

// Generated target file
{
  "welcome": "Bienvenido",
  "system": {
    "component": "Lingo.dev Engine"
  },
  "legal": {
    "privacy": "Privacy policy text"
  }
}

legal/privacy를 스페인어로 수동 번역한 후, 후속 실행에서도 수동 번역이 유지됩니다. system/component 키는 타겟 파일 콘텐츠와 관계없이 항상 영어로 유지됩니다.