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

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.

Initialize a new site with npx [email protected] website classic (like this one).

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.

Please help us complete those default translations.

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/current
cp -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-blog
cp -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-pages
cp -r src/pages/**.md i18n/fr/docusaurus-plugin-content-pages
cp -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