메인 컨텐츠로 이동
버전: 2.2.0

i18n - 따라해보기

도큐사우루스 i18n 시스템이 어떻게 동작하는지 간단한 예제를 따라해보면서 살펴봅니다.

영어로 만든 도큐사우루스 웹 사이트에 프랑스어 번역을 추가해볼 겁니다.

npx [email protected] website classic 명령으로 새로운 사이트를 초기화합니다(이런 형태 파일 구조가 만들어집니다).

사이트 설정하기​

프랑스어 i18n 지원에 필요한 설정을 docusaurus.config.js 파일에 추가합니다.

사이트 설정​

사이트 i18n 설정을 참조해 i18n locales 항목을 아래와 같이 설정합니다.

docusaurus.config.js
module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'fa'],
    localeConfigs: {
      en: {
        htmlLang: 'en-GB',
      },
      // 기본값을 재정의할 필요가 없는 경우 로케일(fr 같은)은 생략할 수 있습니다.
      fa: {
        direction: 'rtl',
      },
    },
  },
};

로케일 이름은 번역된 파일 위치와 번역된 로케일 base URL에 사용됩니다. 모든 로케일 빌드 시 기본 로케일만 base URL에서 이름이 생략됩니다.

도큐사우루스는 로케일 이름을 사용해 <html lang="..."> 속성, 로케일 라벨, 달력 포맷 등에 적절한 기본값을 제공합니다. 기본값은 localeConfigs에서 수정할 수 있습니다.

테마 설정​

원하는 로케일을 선택할 수 있도록 navbar item 항목의 type 값을 localeDropdown으로 설정합니다.

docusaurus.config.js
module.exports = {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
          position: 'left',
        },
      ],
    },
  },
};

사이트 시작하기​

선택한 로케일 옵션으로 번역된 사이트를 개발 모드에서 시작합니다.

npm run start -- --locale fr

http://localhost:3000/fr/ 주소로 여러분의 번역된 사이트에 접근할 수 있습니다.

기본으로 제공되는 번역은 없습니다. 최초 생성되는 사이트는 번역되지 않는 상태로 만들어집니다.

팁

"다음"이나 "이전" 같은 도큐사우루스 기본 테마에 포함된 표현들은 번역을 제공합니다.

기본 번역이 적절하게 제공될 수 있도록 참여를 부탁드립니다.

주의

각 로케일은 별개의 독립적인 단일 페이지 애플리케이션입니다. 모든 로케일의 도큐사우루스 사이트를 동시에 시작할 수는 없습니다.

사이트 번역하기​

프랑스어 로케일에 대한 모든 번역 데이터는 website/i18n/fr에 저장됩니다. 각 플러그인은 해당 폴더 아래에 자체 번역된 콘텐츠를 제공하지만 리액트 코드에 사용되는 모든 텍스트 라벨은 code.json 파일에서 설정합니다.

참고

파일을 복사하고 npm run start -- --locale fr 명령으로 사이트를 다시 시작합니다. 복사한 파일을 편집할 때는 변경된 부분만 반영(Hot-reload)할 수 있습니다.

리액트 코드 번역하기​

직접 작성한 모든 리액트 코드(리액트 페이지, 리액트 컴포넌트 등)에 대해 번역 API를 사용합니다.

사용자에게 표시될 리액트 코드의 모든 텍스트 라벨을 찾아 번역 API를 적용하세요. API는 두 가지 종류가 있습니다.

  • <Translate> 컴포넌트는 문자열을 JSX 요소로 래핑합니다.
  • translate() 콜백 함수는 메시지를 받아 문자열을 반환합니다.

상황에 따라 더 적절한 것을 사용하세요. 예를 들어 <Translate>는 리액트 자식 요소로 사용할 수 있지만 문자열이 필요한 속성인 경우에는 콜백 함수를 사용할 수 있습니다.

주의

JSX 요소는 문자열이 아니라 오브젝트입니다. 문자열로 처리되는 상황(예를 들어 <option>의 자식)에서 이를 사용하면 문자열로 강제 변환되어 "[object Object]" 형태로 반환됩니다. <Translate>를 JSX 자식으로 사용할 것을 권장하며 실제 적용 시에는 요소 형식만을 사용해야 합니다.

src/pages/index.js
import React from 'react';
import Layout from '@theme/Layout';
import Link from '@docusaurus/Link';

export default function Home() {
  return (
    <Layout>
      <h1>Welcome to my website</h1>
      <main>
        You can also visit my
        <Link to="https://docusaurus.io/blog">blog</Link>
        <img
          src="/img/home.png"
          alt="Home icon"
        />
      </main>
    </Layout>
  );
}
정보

도큐사우루스는 의도적으로 번역 기능을 매우 작고 가볍게 제공합니다. ICU 메시지 형식의 하위 집합을 사용해 기본 틀을 채우는 방식을 지원합니다.

대부분의 문서 웹 사이트는 일반적으로 정적인 파일로 구성됩니다. 때문에 i18n 고급 기능(plurals, genders 등)을 사용할 필요는 없습니다. 고급 기능을 사용하고 싶다면 react-intl 같은 라이브러리를 사용하세요.

docusaurus write-translations 명령은 사이트에서 사용하는 모든 리액트 코드 파일을 정적으로 분석하고 API에 대한 호출을 찾아서 code.json 파일에 모아놓습니다. 번역 파일은 ID부터 번역 메시지 오브젝트(번역된 라벨과 라벨에 대한 설명 포함)까지를 맵 형태로 저장합니다. 번역 API(<Translate> 또는 translate()) 호출 시 도큐사우루스가 각 번역 항목을 API 호출을 적절하게 연결하려면 번역되지 않은 기본 메시지나 ID를 지정해야 합니다.

텍스트 라벨은 정적이어야 합니다

docusaurus write-translations 명령은 코드에 대한 정적 분석만 수행합니다. 여러분의 사이트에서 실제 동작하지는 않습니다. 메시지는 문자열이 아닌 표현식이라서 메시지를 추출할 수 없습니다.

const items = [
  {id: 1, title: 'Hello'},
  {id: 2, title: 'World'},
];

function ItemsList() {
  return (
    <ul>
      {/* 사용하지 마세요: write-translations 명령으로 동작하지 않습니다 */}
      {items.map((item) => (
        <li key={item.id}>
          <Translate>{item.title}</Translate>
        </li>
      ))}
    <ul>
  );
}

이것은 런타임에서 올바르게 작동하긴 합니다. 하지만 향후에는 "no-runtime" 메커니즘을 제공해 런타임 시 API를 호출하는 대신 Babel transformation을 통해 리액트 코드에서 번역을 인라인으로 삽입할 수 있게 할겁니다. 따라서 미래를 대비하려면 항상 정적 분석이 가능한 메시지를 선호해야 합니다. 예를 들어 위의 코드는 다음과 같이 리팩토링할 수 있습니다.

const items = [
  {id: 1, title: <Translate>Hello</Translate>},
  {id: 2, title: <Translate>World</Translate>},
];

function ItemsList() {
  return (
    <ul>
      {/* 렌더링 시 제목이 이미 번역된 상태입니다! */}
      {items.map((item) => (
        <li key={item.id}>{item.title}</li>
      ))}
    <ul>
  );
}

번역 API에 대한 호출은 도큐사우루스에 "번역된 메시지로 대체할 텍스트 라벨이 있다"고 알려주는 마커 역할만 하게 됩니다.

복수화​

write-translations을 실행하면 일부 라벨이 복수화되었음을 알 수 있습니다.

i18n/en/code.json
{
  // ...
  "theme.blog.post.plurals": "One post|{count} posts"
  // ...
}

모든 언어에는 가능한 복수 카테고리 목록이 있습니다. 도큐사우루스는 ["zero", "one", "two", "few", "many", "other"]의 순서로 정렬합니다. 예를 들어 영어(en)에는 두 가지 복수형("one", "other")이 있으므로 번역 메시지는 파이프(|)로 구분된 두 개 라벨이 있습니다. 폴란드어(pl)는 세 가지 복수형("one", "few", "many")이 있어 파이프로 연결된 세 개의 라벨을 순서대로 제공합니다.

여러분의 코드 메시지를 복수화할 수도 있습니다.

import {translate} from '@docusaurus/Translate';
import {usePluralForm} from '@docusaurus/theme-common';

function ItemsList({items}) {
  // `usePluralForm`은 현재 로케일에 대한 복수형 선택기를 제공합니다.
  const {selectMessage} = usePluralForm();
  // `items.length`에 따라 적절한 복수형 라벨을 선택합니다.
  const message = selectMessage(
    items.length,
    translate(
      {message: 'One item|{count} items'},
      {count: items.length},
    ),
  );
  return (
    <>
      <h2>{message}</h2>
      <ul>{items.map((item) => <li key={item.id}>{item.title}</li>)}<ul>
    </>
  );
}
참고

도큐사우루스는 복수형을 확인하고 선택하기 위해 Intl.PluralRules를 사용합니다. selectMessage가 작동하려면 적절한 수의 복수형을 올바른 순서로 제공하는 것이 중요합니다.

플러그인 데이터 번역하기​

코드에 산재된 모든 항목에 JSON 번역 파일이 사용됩니다.

  • 위에서 처리한 번역된 라벨을 포함한 리액트 코드
  • 테마 설정 내에 메뉴바와 푸터 라벨
  • sidebars.js의 문서 사이드바 카테고리 라벨
  • 플러그인 옵션의 블로그 사이드바 제목
  • ...

아래와 같이 write-translations 명령을 실행합니다.

npm run write-translations -- --locale fr

명령이 실행되면 번역이 필요한 항목을 추출해서 JSON 번역 파일을 초기화합니다. 루트의 code.json 파일에는 소스 코드에서 추출된 모든 번역 API 호출이 포함되어 있습니다. 이 호출은 사용자가 작성하거나 테마에서 제공될 수 있으며 그 중 일부는 이미 기본 번역되어 있을 수 있습니다.

i18n/fr/code.json
{
  // <Translate> 컴포넌트에 대한 ID가 없음: 기본 메시지가 ID로 사용됩니다
  "Welcome to my website": {
    "message": "Welcome to my website"
  },
  "home.visitMyBlog": {
    "message": "You can also visit my {blog}",
    "description": "The homepage message to ask the user to visit my blog"
  },
  "homepage.visitMyBlog.linkLabel": {
    "message": "Blog",
    "description": "The label for the link to my blog"
  },
  "Home icon": {
    "message": "Home icon",
    "description": "The homepage icon alt message"
  }
}

플러그인이나 테마도 아래와 같은 JSON 번역 파일을 가지고 있습니다.

i18n/fr/docusaurus-theme-classic/navbar.json
{
  "title": {
    "message": "My Site",
    "description": "The title in the navbar"
  },
  "item.label.Docs": {
    "message": "Docs",
    "description": "Navbar item with label Docs"
  },
  "item.label.Blog": {
    "message": "Blog",
    "description": "Navbar item with label Blog"
  },
  "item.label.GitHub": {
    "message": "GitHub",
    "description": "Navbar item with label GitHub"
  }
}

i18n/fr 디렉터리에 있는 JSON 파일의 message 항목을 번역하면 여러분의 사이트 레이아웃과 홈페이지가 번역되는 것입니다.

마크다운 파일 번역하기​

공식적인 도큐사우루스 콘텐츠 플러그인은 다양한 부분에 마크다운/MDX 파일을 사용하며 이를 번역할 수 있습니다.

문서 번역하기​

마크다운 파일을 docs/에서 i18n/fr/docusaurus-plugin-content-docs/current로 복사하고 이를 번역합니다.

mkdir -p i18n/fr/docusaurus-plugin-content-docs/current
cp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current
정보

docusaurus-plugin-content-docs 플러그인은 항상 콘텐츠를 버전에 따라 나누는 것에 유의하세요. ./docs 폴더의 데이터는 current 하위 폴더와 current.json 파일로 번역됩니다. "현재(current)"의 의미에 대한 자세한 내용은 문서 버전 관리 가이드를 참고하세요.

블로그 번역하기​

블로그 마크다운 파일을 i18n/fr/docusaurus-plugin-content-blog 디렉터리 아래에 복사하고 이를 번역합니다.

mkdir -p i18n/fr/docusaurus-plugin-content-blog
cp -r blog/** i18n/fr/docusaurus-plugin-content-blog

페이지 번역하기​

페이지 마크다운 파일을 i18n/fr/docusaurus-plugin-content-pages 디렉터리 아래에 복사하고 이를 번역합니다.

mkdir -p i18n/fr/docusaurus-plugin-content-pages
cp -r src/pages/**.md i18n/fr/docusaurus-plugin-content-pages
cp -r src/pages/**.mdx i18n/fr/docusaurus-plugin-content-pages
주의

리액트 페이지는 JSON 번역 파일에서 번역하기 때문에 .md, .mdx 파일만 복사하면 됩니다.

명시적인 제목 ID 사용하기

기본적으로 마크다운에서 제목으로 ### Hello World을 설정하면 hello-world로 ID가 만들어집니다. 다른 문서에서 링크를 연결할 때는 [link](#hello-world) 형식을 사용합니다. 하지만 번역 후에 제목은 ### Bonjour le Monde이 되고 ID는 bonjour-le-monde이 됩니다.

이렇게 만들어지는 ID가 번역된 사이트에 항상 적합한 것은 아닙니다. 여러분이 적절한 링크를 직접 수정해주어야 합니다.

- [link](#hello-world).
+ [link](#bonjour-le-monde)

번역된 사이트는 명시적인 제목 ID를 사용하는 것을 권장합니다.

사이트를 배포합니다.​

여러분의 사이트는 하나의 도메인을 사용할 수도 있고 여러(하위) 도메인을 사용할 수도 있습니다.

단일 도메인에 배포하기​

아래 명령을 실행합니다.

npm run build

도큐사우루스는 로케일 별로 하나의 단일 페이지 애플리케이션을 만듭니다.

  • website/build: 기본값으로 영어 애플리케이션을 만듭니다.
  • website/build/fr: 프랑스어 애플리케이션을 위한 디렉터리입니다.

여러분은 이제 원하는 호스팅 서비스에 build 디렉터리를 배포할 수 있습니다.

참고

도큐사우루스 v2 웹 사이트는 아래와 같은 형태를 사용합니다.

팁

호스팅 서비스에서는 일반적으로 /unknown/url 페이지는 규칙에 따라 /404.html로 리다이렉트합니다. 해당 페이지는 영어로 작성된 404 페이지를 보여줍니다.

/fr/* 하위 디렉터리 페이지는 /fr/404.html로 리다이렉트할 수 있도록 호스팅 서비스를 설정하면 여러분의 언어에 맞는 404 페이지를 처리할 수 있습니다.

모든 호스팅 서비스에서 지원하는 건 아닙니다. 깃허브 페이지는 지원하지 않으며 네트리파이(Netlify)는 지원합니다.

여러 도메인에 배포하기​

하나의 로케일만 지원하도록 사이트를 빌드할 수 있습니다.

npm run build -- --locale fr

도큐사우루스에서는 /fr/ URL 접두사를 추가하지 않습니다.

여러분이 이용하는 호스팅 서비스에서 아래와 같은 작업이 필요합니다.

  • 로케일마다 배포 파일을 만듭니다.
  • --locale 옵션을 사용해 적절한 빌드 명령을 설정합니다.
  • 선택한 배포 대상에 따라 (하위) 도메인을 설정해줍니다.
주의

위에서 설명한 방법은 깃허브 페이지에서는 사용할 수 없습니다. 개별적인 배포 방식에 한정된 방법입니다.

혼합 방식​

일부는 하위 경로 일부는 하위 도메인을 사용하도록 설정할 수 있습니다.

각 로케일 파일을 별도의 하위 도메인에 배포하고 CDN 수준에서 하나의 통합된 도메인의 하위 도메인으로 조합할 수 있습니다.

  • 사이트를 fr.docusaurus.io에 배포합니다.
  • CDN 설정으로 docusaurus.io/fr에서 서비스가 되도록 합니다.

번역 관리​

도큐사우루스에서는 여러분이 번역 결과를 관리하는 방법은 신경쓰지 않습니다. 빌드 시 파일 시스템에서 모든 번역 파일(JSON, 마크다운, 기타 데이터 파일)을 사용할 수 있게 지원할 뿐입니다. 하지만 사이트 관리자는 번역에 기여하는 이들이 원활하게 협업할 수 있도록 번역을 관리하는 방법을 고려해야 합니다.

우리는 두 가지 일반적인 번역 시 협업 전략을 공유해드릴 수 있습니다. 깃 사용하기 and 크라우드인 사용하기