Handlebars

Lingo.dev CLI로 Handlebars 템플릿 현지화하기

Handlebars란 무엇인가요?

Handlebars는 의미론적 템플릿을 효과적으로 구축할 수 있는 강력한 기능을 제공하는 인기 있는 템플릿 엔진입니다. 깔끔한 구문을 사용하고 템플릿을 JavaScript 함수로 컴파일하여 클라이언트 측 및 서버 측 애플리케이션 모두에서 HTML 생성에 널리 사용됩니다.

Lingo.dev CLI란 무엇인가요?

Lingo.dev CLI는 AI로 앱과 콘텐츠를 번역하기 위한 무료 오픈 소스 CLI입니다. 기존 파이프라인과 통합하면서 기존 번역 관리 소프트웨어를 대체하도록 설계되었습니다.

자세한 내용은 개요를 참조하세요.

이 가이드에 대하여

이 가이드는 Lingo.dev CLI를 사용하여 Handlebars 템플릿을 현지화하는 방법을 설명합니다.

다음 내용을 배우게 됩니다:

  • Handlebars 프로젝트를 위한 번역 파일 구조화
  • 번역 파이프라인 구성
  • AI로 번역 생성

사전 요구 사항

Lingo.dev CLI를 사용하려면 Node.js v18+ 이상이 설치되어 있어야 합니다:

❯ node -v
v22.17.0

Handlebars 현지화 접근 방식

Handlebars 템플릿은 하드코딩된 텍스트를 포함하는 대신 JSON 파일에서 번역 가능한 콘텐츠를 참조해야 합니다. 이 접근 방식은 다음을 제공합니다:

  • 명확한 분리: 템플릿 구조 vs 번역 가능한 콘텐츠
  • 버전 관리: JSON 파일에서 추적되는 번역
  • 모호함 없음: 번역 가능한 항목을 명시적으로 정의

템플릿에서 번역에 액세스하려면 번역 헬퍼 함수가 필요합니다. 일반적인 옵션은 다음과 같습니다:

간단한 커스텀 헬퍼:

{{t "product.title"}}
{{t "greeting" name="John"}}

handlebars-i18n - 포맷팅 기능이 풍부함:

{{__ "product.title"}}
{{_date releaseDate}}
{{_price amount "USD"}}

npm | GitHub

handlebars-i18next - 대체 i18next 통합:

{{t "product.title"}}

npm | GitHub

이 가이드는 예제에서 {{t}}를 사용하지만, 워크플로는 모든 헬퍼 선택에 적용됩니다.

1단계. 프로젝트 설정

프로젝트 디렉토리에서 i18n.json 파일을 생성하세요:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

이 파일은 번역할 언어와 파일 시스템에서 현지화 가능한 콘텐츠가 존재하는 위치를 포함하여 번역 파이프라인의 동작을 정의합니다.

사용 가능한 속성에 대해 자세히 알아보려면 i18n.json을 참조하세요.

2단계. 소스 로케일 구성

_소스 로케일_은 콘텐츠가 작성된 원본 언어 및 지역입니다. 소스 로케일을 구성하려면 i18n.json 파일에서 locale.source 속성을 설정하세요:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

소스 로케일은 BCP 47 언어 태그로 제공되어야 합니다.

Lingo.dev CLI가 지원하는 로케일 코드의 전체 목록은 지원되는 로케일 코드를 참조하세요.

3단계. 타겟 로케일 구성

_타겟 로케일_은 콘텐츠를 번역하려는 언어 및 지역입니다. 타겟 로케일을 구성하려면 i18n.json 파일에서 locale.targets 속성을 설정하세요:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

4단계. 소스 콘텐츠 생성

번역 가능한 콘텐츠가 포함된 JSON 파일을 생성하세요. 이러한 파일은 소스 로케일 코드를 포함하는 디렉토리 구조로 구성되어야 합니다:

project/
├── locales/
│   └── en/
│       ├── common.json
│       └── store.json
├── templates/
│   └── product.handlebars
└── i18n.json

es/ 디렉토리와 번역된 파일은 8단계에서 번역을 생성할 때 Lingo.dev CLI에 의해 자동으로 생성됩니다.

JSON 파일 예제

locales/en/common.json:

{
  "navigation": {
    "home": "Home",
    "products": "Products",
    "about": "About",
    "contact": "Contact"
  },
  "footer": {
    "copyright": "All rights reserved",
    "privacy": "Privacy Policy",
    "terms": "Terms of Service"
  }
}

locales/en/store.json:

{
  "product": {
    "title": "Wireless Headphones",
    "description": "Premium sound quality with active noise cancellation",
    "price": "Price",
    "inStock": "In Stock",
    "outOfStock": "Out of Stock"
  },
  "cart": {
    "add": "Add to Cart"
  },
  "actions": {
    "buyNow": "Buy Now"
  }
}

5단계. 버킷 생성

  1. i18n.json 파일에서 buckets 객체에 "json" 객체를 추가하세요:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "json": {}
  }
}

  2. "json" 객체에서 하나 이상의 include 패턴 배열을 정의하세요:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "json": {
      "include": ["./locales/[locale]/*.json"]
    }
  }
}

    이 패턴들은 번역할 파일을 정의합니다.

    패턴 자체는:

    • 구성된 로케일의 플레이스홀더로 [locale]를 포함해야 합니다
    • 파일 경로를 가리킬 수 있습니다 (예: "locales/[locale]/common.json")
    • 와일드카드 플레이스홀더로 별표를 사용할 수 있습니다 (예: "locales/[locale]/*.json")

    재귀적 glob 패턴 (예: **/*.json)은 지원되지 않습니다.

6단계. 템플릿에서 번역 사용하기

선택한 헬퍼를 사용하여 Handlebars 템플릿에서 번역 키를 참조하세요:

templates/product.handlebars:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>{{t "product.title"}}</title>
</head>
<body>
  <nav>
    <a href="/">{{t "navigation.home"}}</a>
    <a href="/products">{{t "navigation.products"}}</a>
    <a href="/about">{{t "navigation.about"}}</a>
    <a href="/contact">{{t "navigation.contact"}}</a>
  </nav>

  <main>
    <article>
      <h1>{{t "product.title"}}</h1>
      <p>{{t "product.description"}}</p>

      <div class="price">
        <span>{{t "product.price"}}:</span>
        <span>$299.99</span>
      </div>

      <div class="stock">
        {{#if inStock}}
          <span class="available">{{t "product.inStock"}}</span>
        {{else}}
          <span class="unavailable">{{t "product.outOfStock"}}</span>
        {{/if}}
      </div>

      <div class="actions">
        <button class="primary">{{t "cart.add"}}</button>
        <button class="secondary">{{t "actions.buyNow"}}</button>
      </div>
    </article>
  </main>

  <footer>
    <p>{{t "footer.copyright"}}</p>
    <a href="/privacy">{{t "footer.privacy"}}</a>
    <a href="/terms">{{t "footer.terms"}}</a>
  </footer>
</body>
</html>

이러한 번역을 로드하고 템플릿을 컴파일하는 방법은 빌드 설정과 선택한 헬퍼 라이브러리에 따라 다릅니다.

7단계. LLM 구성하기

Lingo.dev CLI는 대규모 언어 모델(LLM)을 사용하여 AI로 콘텐츠를 번역합니다. 이러한 모델 중 하나를 사용하려면 지원되는 제공업체의 API 키가 필요합니다.

가능한 한 빠르게 시작하려면 Lingo.dev Engine 사용을 권장합니다:

  1. Lingo.dev 계정에 가입하세요.

  2. 다음 명령을 실행하세요:

    npx lingo.dev@latest login

    기본 브라우저가 열리고 인증을 요청합니다.

  3. 안내에 따라 진행하세요.

8단계. 번역 생성하기

i18n.json 파일이 있는 디렉토리에서 다음 명령을 실행하세요:

npx lingo.dev@latest run

이 명령은:

  1. i18n.json 파일을 읽습니다.
  2. 번역이 필요한 JSON 파일을 찾습니다.
  3. 파일에서 번역 가능한 콘텐츠를 추출합니다.
  4. 구성된 LLM을 사용하여 추출된 콘텐츠를 번역합니다.
  5. 번역된 콘텐츠를 파일 시스템에 다시 작성합니다.

번역이 처음 생성될 때 i18n.lock 파일이 생성됩니다. 이 파일은 어떤 콘텐츠가 번역되었는지 추적하여 후속 실행 시 불필요한 재번역을 방지합니다.

예제

프로젝트 구조

handlebars-localization/
├── locales/
│   ├── en/
│   │   ├── common.json
│   │   └── store.json
│   └── es/
│       ├── common.json
│       └── store.json
├── templates/
│   └── product.handlebars
└── i18n.json

locales/en/common.json

{
  "navigation": {
    "home": "Home",
    "products": "Products",
    "about": "About",
    "contact": "Contact"
  },
  "footer": {
    "copyright": "All rights reserved",
    "privacy": "Privacy Policy",
    "terms": "Terms of Service"
  }
}

locales/en/store.json

{
  "product": {
    "title": "Wireless Headphones",
    "description": "Premium sound quality with active noise cancellation",
    "price": "Price",
    "inStock": "In Stock",
    "outOfStock": "Out of Stock"
  },
  "cart": {
    "add": "Add to Cart"
  },
  "actions": {
    "buyNow": "Buy Now"
  }
}

locales/es/common.json

{
  "navigation": {
    "home": "Inicio",
    "products": "Productos",
    "about": "Acerca de",
    "contact": "Contacto"
  },
  "footer": {
    "copyright": "Todos los derechos reservados",
    "privacy": "Política de privacidad",
    "terms": "Términos de servicio"
  }
}

locales/es/store.json

{
  "product": {
    "title": "Auriculares inalámbricos",
    "description": "Calidad de sonido premium con cancelación activa de ruido",
    "price": "Precio",
    "inStock": "En stock",
    "outOfStock": "Agotado"
  },
  "cart": {
    "add": "Añadir al carrito"
  },
  "actions": {
    "buyNow": "Comprar ahora"
  }
}

templates/product.handlebars

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>{{t "product.title"}}</title>
</head>
<body>
  <nav>
    <a href="/">{{t "navigation.home"}}</a>
    <a href="/products">{{t "navigation.products"}}</a>
    <a href="/about">{{t "navigation.about"}}</a>
    <a href="/contact">{{t "navigation.contact"}}</a>
  </nav>

  <main>
    <article>
      <h1>{{t "product.title"}}</h1>
      <p>{{t "product.description"}}</p>

      <div class="price">
        <span>{{t "product.price"}}:</span>
        <span>$299.99</span>
      </div>

      <div class="stock">
        {{#if inStock}}
          <span class="available">{{t "product.inStock"}}</span>
        {{else}}
          <span class="unavailable">{{t "product.outOfStock"}}</span>
        {{/if}}
      </div>

      <div class="actions">
        <button class="primary">{{t "cart.add"}}</button>
        <button class="secondary">{{t "actions.buyNow"}}</button>
      </div>
    </article>
  </main>

  <footer>
    <p>{{t "footer.copyright"}}</p>
    <a href="/privacy">{{t "footer.privacy"}}</a>
    <a href="/terms">{{t "footer.terms"}}</a>
  </footer>
</body>
</html>

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "json": {
      "include": ["./locales/[locale]/*.json"]
    }
  }
}

i18n.lock

version: 1
checksums:
  8a4f2c9e1d6b3a7f5e8c2d1b9a3f6e4c:
    navigation.home: 7b2e4f9a1c8d3b6f5e2a9d1c8b4f7e3a
    navigation.products: 3f8e2a9d1c6b4f7e5a2c9d1b8f4e7a3b
    navigation.about: 9d1c8b4f7e3a2f9e1d6b3a7f5e8c2d1b
    navigation.contact: 4f7e3a2c9d1b8f6e5a3f2d9c1b7e4a8f
    footer.copyright: 2c9d1b8f4e7a3b6f5e2a9d1c8b4f7e3a
    footer.privacy: 8b4f7e3a2c9d1b6f5e2a9d1c8f4e7a3b
    footer.terms: 6f5e2a9d1c8b4f7e3a2c9d1b8f4e7a3b
  3b6f5e2a9d1c8b4f7e3a2c9d1b8f4e7a:
    product.title: 1c8b4f7e3a2c9d1b6f5e2a9d1c8f4e7a
    product.description: 7e3a2c9d1b6f5e2a9d1c8b4f7e3a2c9d
    product.price: 9d1b6f5e2a9d1c8b4f7e3a2c9d1b8f4e
    product.inStock: 4f7e3a2c9d1b6f5e2a9d1c8b4f7e3a2c
    product.outOfStock: 2c9d1b6f5e2a9d1c8b4f7e3a2c9d1b8f
    cart.add: 8b4f7e3a2c9d1b6f5e2a9d1c8b4f7e3a
    actions.buyNow: 7e3a2c9d1b6f5e2a9d1c8b4f7e3a2c9d