Version: 2.0.0-beta.4

i18n - 따라해보기

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

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

npx @docusaurus/init@latest init website classic 명령으로 새로운 사이트를 초기화합니다(이런 형태 파일 구조가 만들어집니다).

사이트 설정하기#

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

사이트 설정#

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

docusaurus.config.js

module.exports = {  i18n: {    defaultLocale: 'en',    locales: ['en', 'fr'],  },};

테마 설정#

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

docusaurus.config.js

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

사이트 시작하기#

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

npm
Yarn

npm run start -- --locale fr

yarn run start -- --locale fr

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

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

tip

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

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

caution

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

사이트 번역하기#

프랑스어 번역은 website/i18n/fr 디렉터리 아래에 추가됩니다.

도큐사우루스는 모듈 형태입니다. 각 콘텐츠 플러그인은 자체 하위 디렉터리를 가지고 있습니다.

note

파일을 복사하고 npm run start -- --locale fr 명령으로 사이트를 다시 시작합니다.

복사한 파일을 편집할 때는 변경된 부분만 반영(Hot-reload)할 수 있습니다.

translation API 사용하기#

홈페이지를 열고 translation APIs를 사용할 수 있습니다.

src/pages/index.js

import React from 'react';import Layout from '@theme/Layout';import Link from '@docusaurus/Link';
import Translate, {translate} from '@docusaurus/Translate';
export default function Home() {  return (    <Layout>      <h1>        <Translate>Welcome to my website</Translate>      </h1>      <main>        <Translate          id="homepage.visitMyBlog"          description="The homepage message to ask the user to visit my blog"          values={{blog: <Link to="https://docusaurus.io/blog">blog</Link>}}>          {'You can also visit my {blog}'}        </Translate>
        <input          type="text"          placeholder={            translate({              message: 'Hello',              description: 'The homepage input placeholder',            })          }        />      </main>    </Layout>  );}

caution

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

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

JSON 파일 번역하기#

마크다운 문서에 포함되지 않는 모든 항목에 JSON 번역 파일이 사용됩니다.

React/JSX 코드
메뉴바나 푸터 레이아웃에서 사용하는 라벨
문서 사이드바 카테고리 라벨
...

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

npm
Yarn

npm run write-translations -- --locale fr

yarn run write-translations -- --locale fr

명령이 실행되면 번역이 필요한 항목을 추출해서 JSON 번역 파일을 초기화합니다.

리액트 소스 코드에서 뽑아낸 홈페이지 번역 항목입니다.

i18n/fr/code.json

{  "Welcome to my website": {    "message": "Welcome to my website",    "description": "The homepage welcome message"  },  "Hello": {    "message": "Hello",    "description": "The homepage input placeholder"  }}

플러그인이나 테마도 아래와 같은 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 파일을 사용하며 이를 번역할 수 있습니다.

문서 번역하기#

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

mkdir -p i18n/fr/docusaurus-plugin-content-docs/currentcp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current

info

current는 문서 버전 기능 사용 시 필요한 디렉터리입니다. 각 문서 버전은 하위 디렉터리를 가지고 있습니다.

블로그 번역하기#

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

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

페이지 번역하기#

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

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

caution

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

명시적인 제목(heading) id 사용하기#

기본적으로 마크다운에서 제목으로 ### Hello World을 설정하면 hello-world로 id가 만들어집니다.

다른 문서에서 링크를 연결할 때는 [link](#hello-world) 형식을 사용합니다.

번역된 제목도 마찬가지로 ### Bonjour le Monde을 설정하면 bonjour-le-monde가 id로 만들어집니다.

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

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

tip

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

사이트를 배포합니다.#

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

단일 도메인에 배포하기#

아래 명령을 실행합니다.

npm
Yarn

npm run build

yarn run build

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

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

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

note

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

tip

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

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

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

여러 도메인에 배포하기#

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

npm
Yarn

npm run build -- --locale fr

yarn run build -- --locale fr

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

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

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

caution

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

혼합 방식#

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

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

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