Ir para o conteúdo principal
Version: 2.0.0-beta.3

i18n - Tutorial

Esse tutorial o guiará pelo sistema Docusaurus i18n.

Nós iremos adicionar traduções de francês a um recém-inicializado site em Inglês Docusaurus.

Inicialize um novo site com npx @docusaurus/init@latest init website classic (como esse).

Configure seu site#

Modifique o docusaurus.config.js para adicionar o suporte do i18n para a língua francesa.

Configuração do site#

Use a configuração i18n do site para declarar as localidades i18n:

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

Configuração do tema#

Adicione um item da barra de navegação do tipo localeDropdown para que os usuários possam selecionar a localidade que quiserem:

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

Iniciar seu site#

Inicie seu site localizado no modo de desenvolvimento, usando a localidade de sua escolha:

npm run start -- --locale fr

Seu site está acessível em http://localhost:3000/fr/.

Não fornecemos nenhuma tradução e o site é na sua maioria não traduzido.

tip

O Docusaurus fornece traduções padrão para nomes genéricos de temas, tais como "Próximo" e "Anterior" para a paginação.

Por favor, ajude-nos a completar as traduções padrão.

caution

Cada local é uma single-page-application autônoma distinta: não é possível iniciar os sites Docusaurus em todos os locais ao mesmo tempo.

Traduzir o seu site#

As traduções francesas serão adicionadas no website/i18n/fr.

Docusaurus é modular e cada plugin de conteúdo tem sua própria subpasta.

note

Depois de copiar os arquivos, reinicie seu site com npm run start - --locale fr.

O hot-reload funcionará melhor ao editar arquivos existentes.

Use as APIs de tradução#

Abra a página inicial e use as APIs de tradução:

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

Docusaurus fornece um tempo de execução de tradução muito baixo e leve propositalmente e só oferece suporte a interpolação de marcadores de posição, usando um subconjunto do Formato de mensagem ICU.

A maioria dos sites de documentação são geralmente estáticos e não precisam de recursos i18n avançados (plurais, gêneros, etc.). Use uma biblioteca como react-intl para casos de uso mais avançados.

Traduzir arquivos JSON#

Os arquivos de tradução JSON são usados para tudo o que não está contido em um documento Markdown:

  • Código React/JSX
  • Layout da barra de navegação e rótulos de rodapé
  • Rótulos de categoria da barra lateral do Documentos
  • ...

Execute o comando write-translations:

npm run write-translations -- --locale fr

Ele irá extrair e inicializar os arquivos de tradução JSON que você precisa traduzir.

As traduções da página inicial são extraídas estaticamente do código fonte do React:

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"  }}

Plugins e temas também escreverão seus próprios arquivos de tradução JSON, tais como:

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"  }}

Traduza o atributomensagem nos arquivos JSON de i18n/fr, e o layout do seu site e a página inicial agora devem ser traduzidos.

Traduzir arquivos Markdown#

Os plug-ins de conteúdo oficial do Docusaurus usam extensivamente arquivos Markdown/MDX e permitem que você os traduza.

Traduzir os documentos#

Copie seus arquivos Markdown de documentos para i18n/fr/docusaurus-plugin-content-docs/current e traduza-os:

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

current é necessário para o recurso de versionamento de documentos: cada versão de documentos tem sua própria subpasta.

Traduzir o blog#

Copie os arquivos Markdown do seu blog para i18n/fr/docusaurus-plugin-content-blog e traduza-os:

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

Traduzir as páginas#

Copie os arquivos Markdown de suas páginas para i18n/fr/docusaurus-plugin-content-pages e traduza:

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

Nós apenas copiamos os arquivos .md e .mdx, pois os componentes React das páginas já foram traduzidos por meio de arquivos de tradução JSON.

Use ids de cabeçalho explícitos#

Por padrão, um título do Markdown ### Hello World terá um id gerado hello-world.

Outros documentos podem se referenciar a ele com [link](#hello-world).

O título traduzido se torna ### Bonjour le Monde, com id bonjour-le-monde.

Os ids gerados nem sempre são adequados para sites localizados, pois exigem que você localize todos os links âncora:

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

Para sites localizados, é recomendado usar ids de cabeçalho explícitos.

Deploy do seu site#

Você pode escolher em fazer deploy do seu site em um domínio único ou usar múltiplos (sub)domínios.

Implementação de um domínio#

Execute o seguinte comando:

npm run build

O Docusaurus irá construir uma aplicação única por localidade:

  • website/build: por padrão, língua inglesa
  • website/build/fr: para o idioma francês

Agora você pode fazer deploy e build na solução de hospedagem estática de sua escolha.

note

O site Docusaurus v2 usa essa estratégia:

tip

Provedores de hospedagem estáticos geralmente redireciona /unknown/urls para /404.html por convenção, mostrando sempre uma página em inglês 404.

Localize suas páginas 404 configurando seu host para redirecionar /fr/* para /fr/404.html.

Isso nem sempre é possível e depende do seu host: as páginas do GitHub não podem fazer isso, [Netlify](https://docs.netlify.com/routing/redirects/redirect-options/#custom-404-page- manipulação) pode.

Deploy multi-domínio#

Você também pode criar seu site para uma única localidade:

npm run build -- --locale fr

O Docusaurus não adicionará o prefixo URL /fr/.

No seu provedor de hospedagem estática:

  • crie uma implantação por localidade
  • configure o comando de compilação apropriado, usando a opção --locale
  • configure o (sub)domínio de sua escolha para cada implantação
caution

Essa estratégia não é possível com as páginas do Github, pois só é possível ter uma única implantação.

Híbrido#

É possível ter alguns locais usando subcaminhos e outros usando subdomínios.

Também é possível implantar cada local como um subdomínio separado, montar os subdomínios em um único domínio unificado no nível de CDN:

  • Fazer deploy do seu site como fr.docusaurus.io
  • Configure um CDN para servi-lo a partir de docusaurus.io/fr