Skip to content

t() 호출 및 복수형 ​

소스 코드에서 t() 사용 ​

추출 스크립트가 찾을 수 있도록 sourceLocale에서 리터럴 문자열로 t()을(를) 호출합니다. 해당 언어는 어떤 언어든 될 수 있습니다. 아래 예시에서는 영어를 사용합니다. 하드코딩된 소스 텍스트를 이러한 호출로 변환하려면 JS/TS 앱에 i18n 추가하기를 참조하세요.

jsx
import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t } = useTranslation();
  return <button>{t('Save')}</button>;
}

동일한 패턴이 React 외부(Node.js, 서버 컴포넌트, CLI)에서도 작동합니다:

js
import i18n from './i18n.js';
console.log(i18n.t('Processing complete'));

Python 애플리케이션은 생성된 i18n.py 헬퍼를 사용합니다. Python 애플리케이션을 참조하세요.

규칙:

  • 다음 형식만 추출됩니다: t("…"), t('…'), t(…), i18n.t("…").
  • 키는 리터럴 문자열이어야 합니다 — 변수나 표현식을 키로 사용할 수 없습니다.
  • 키에 템플릿 리터럴을 사용하지 마세요: {'t(Hello ${name})'}은(는) 추출할 수 없습니다.

보간 ​

{{var}} 플레이스홀더에 i18next의 기본 두 번째 인수 보간을 사용하세요:

js
// i18next handles substitution natively, even in key-as-default mode
t('Hello {{name}}, you have {{count}} messages', { name, count })
// → "Hello Alice, you have 3 messages"

추출 명령은 두 번째 인수가 일반 객체 리터럴일 때 이를 파싱하고 plurals: true 및 zeroDigit과 같은 도구 전용 플래그를 읽습니다 (아래의 기수 복수형 참조). 일반 문자열의 경우 리터럴 키만 해싱에 사용되며, 보간 옵션은 런타임에 i18next로 전달됩니다.

프로젝트에서 사용자 지정 보간 유틸리티를 사용하는 경우(예: t('key')를 호출한 후 interpolateTemplate(t('Hello {{name}}'), { name })과 같은 템플릿 함수로 결과를 파이핑), setupKeyAsDefaultT(wrapI18nWithKeyTrim를 통해)을 사용하면 이러한 작업이 불필요해집니다. 소스 로케일이 원시 키를 반환하는 경우에도 {{var}} 보간을 적용합니다. 호출 사이트를 t('Hello {{name}}', { name })로 마이그레이션하고 사용자 지정 유틸리티를 제거하세요.

기수 복수형 (plurals: true) ​

복수형을 직접 작성하지 않습니다. 소스 코드에서 메시지를 한 번 작성하고 두 번째 인수에 두 가지를 전달합니다:

  1. plurals: true — 추출 도구와 translate-ui에 이 호출이 기수 복수 그룹임을 알립니다.
  2. count — 런타임에 올바른 형태를 선택하기 위해 i18next가 사용하는 숫자입니다.
tsx
{t('{{count}} items in your cart', { plurals: true, count: n })}

이것이 호출 사이트에 필요한 전부입니다. _zero, _one, _other 또는 기타 접미사 키를 직접 정의하지 않습니다.

translate-ui을(를) 실행하면 ai-i18n-tools가 LLM을 호출하여 각 대상 로케일(zero, one, two, few, many, other — 해당 언어에 Intl.PluralRules이(가) 필요로 하는 형식)에 필요한 모든 기수 카테고리를 생성합니다. 모델은 원래 리터럴과 소스 언어 복수형 변형을 받은 다음 번역된 형식을 반환합니다. 도구는 이를 strings.json에 기록하고 플랫 i18next JSON(<groupId>_zero, <groupId>_one, …)을 내보내므로 런타임 복수형 확인이 추가 설정 없이 작동합니다.

  • zeroDigit (선택 사항) — 도구 전용; i18next에서 읽지 않습니다. true인 경우, LLM 프롬프트는 해당 형식이 존재하는 각 로케일의 _zero 문자열에서 리터럴 아랍어 0를 선호합니다; false이거나 생략된 경우, 자연스러운 0 표현이 사용됩니다. i18next.t를 호출하기 전에 이 키를 제거하세요 (아래의 wrapT 참조).

유효성 검사: 메시지에 두 개 이상의 고유한 {{…}} 플레이스홀더가 포함된 경우, 그중 하나는 {{count}} (복수형 축)이어야 합니다. 그렇지 않으면 extract이(가) 명확한 파일/라인 메시지와 함께 실패합니다.

LLM이 CLDR 형식을 반환하면, translate-ui은(는) 각 형식을 원본 개발자 리터럴과 비교하고, 소스 언어 형식이 하나의 플레이스홀더 세트를 공유하지 않을 경우 해당 카테고리의 원본 형식과 비교하여 확인합니다. 원본의 모든 플레이스홀더는 모든 카테고리( one 포함)에 나타나야 합니다. .NET Tn 복수형의 {0}와 같이 영어 복수형에만 존재하는 플레이스홀더는 other 및 그 뒤를 따르는 카테고리(many, few, two)에 나타나야 하며, 원본 형식에 해당 플레이스홀더가 없는 카테고리에는 나타나지 않아야 합니다. 형식은 다른 {{…}} / %d / {n} 토큰을 새로 만들어서는 안 됩니다. (플레이스홀더나 숫자가 없는) 명사 전용 소스(예: Minutes와 같은 단위 레이블)는 명사 전용으로 유지되어야 합니다. 불일치가 발생하면 해당 모델의 응답을 폐기하고 대체 목록의 다음 모델을 재시도합니다.

두 개의 독립적인 카운트 (예: 섹션 및 페이지)는 하나의 복수형 메시지를 공유할 수 없습니다 — 두 개의 t() 호출(각각 plurals: true 및 자체 count 포함)을 사용하고 UI에서 연결하세요.

v1에 없는 기능: 서수 복수형 (_ordinal_*, ordinal: true), 구간 복수형, ICU 전용 파이프라인.

복수형 저장 및 출력 방식 ​

에서 strings.json 복수형 그룹은 "plural": true과 함께 해시당 한 행을 사용하며, source에 원본 리터럴을, translated[locale]에는 해당 로케일의 문자열에 카디널 카테고리(zero, one, two, few, many, other)를 매핑하는 객체를 사용합니다.

플랫 로케일 JSON: 비복수형 행은 원본 문장 → 번역을 유지합니다. 복수형 행은 <groupId>_original(참고용으로 source과 동일) 및 각 접미사에 대해 <groupId>_<form>로 출력되어 i18next가 복수형을 기본적으로 해결할 수 있도록 합니다. translate-ui는 또한 오직 복수형 플랫 키만 포함된 {sourceLocale}.json를 작성합니다(접미사가 붙은 키가 해결되도록 소스 언어에 대해 이 번들을 로드하십시오; 일반 문자열은 여전히 키를 기본값으로 사용합니다). 각 대상 로케일에 대해, 출력된 접미사 키는 해당 로케일의 Intl.PluralRules(requiredCldrPluralForms)와 일치합니다: 만약 strings.json이 압축 후 다른 카테고리와 일치하여 생략된 경우(예: 아랍어 many이 other와 동일), translate-ui은 폴백 형제 문자열에서 복사하여 필요한 모든 접미사를 플랫 파일에 작성하므로 런타임 조회 시 키를 놓치는 일이 없습니다.

런타임(ai-i18n-tools/runtime): setupKeyAsDefaultT(i18n, { stringsJson, sourcePluralFlatBundle })을 호출합니다 — 이는 wrapI18nWithKeyTrim를 실행하고, 선택적 translate-ui {sourceLocale}.json 복수형 번들을 등록한 다음, buildPluralIndexFromStringsJson(stringsJson)를 사용하여 wrapT합니다. wrapT은 plurals / zeroDigit를 제거하고, 필요할 때 키를 그룹 ID로 다시 작성하며, count을 전달합니다(선택 사항: {{count}}이 아닌 단일 플레이스홀더가 있는 경우 count은 해당 숫자 옵션에서 복사됩니다). i18next 연결 및 런타임 헬퍼를 참조하십시오.

MIT 라이선스에 따라 배포됩니다.