--- title: Suporte multilíngue description: Ofereça documentação em vários idiomas com um seletor de idioma, navegação própria para cada idioma e conteúdo traduzido. --- > **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version. Se a sua documentação precisa alcançar usuários em mais de um idioma, você pode definir árvores de navegação separadas por localidade e permitir que os leitores alternem entre elas usando um menu suspenso na barra superior. O Jamdesk pode traduzir suas páginas para você — consulte [Tradução por IA](/pt/setup/ai-translation). Esta página aborda a configuração da navegação e do seletor de idioma, aplicável independentemente de as traduções serem feitas pelo Jamdesk, pelos seus próprios tradutores ou por outra ferramenta. ## Configuração Coloque sua navegação dentro de um array `languages`, com cada idioma contendo sua própria estrutura de navegação: ```json docs.json { "navigation": { "languages": [ { "language": "en", "tabs": [ { "tab": "Documentation", "groups": [ { "group": "Getting Started", "pages": ["introduction", "quickstart"] } ] } ] }, { "language": "es", "tabs": [ { "tab": "Documentación", "groups": [ { "group": "Comenzar", "pages": ["es/introduction", "es/quickstart"] } ] } ] } ] } } ``` ## Idiomas compatíveis | Código | Idioma | Código | Idioma | |------|----------|------|----------| | `en` | Inglês | `ko` | Coreano | | `es` | Espanhol | `pt-BR` | Português (Brasil) | | `fr` | Francês | `ru` | Russo | | `de` | Alemão | `ar` | Árabe | | `it` | Italiano | `hi` | Hindi | | `jp` | Japonês | `id` | Indonésio | | `cn` | Chinês (simplificado) | `tr` | Turco | | `zh-Hant` | Chinês (tradicional) | `vi` | Vietnamita | | `nl` | Holandês | `pl` | Polonês | | `sv` | Sueco | `cs` | Tcheco | | `no` | Norueguês | `ro` | Romeno | | `he` | Hebraico | `ua` | Ucraniano | | `lv` | Letão | `uz` | Uzbeque | ## Estrutura de diretórios Organize o conteúdo traduzido em diretórios com o prefixo do idioma: ```bash my-docs/ ├── docs.json ├── introduction.mdx # English (default) ├── quickstart.mdx ├── es/ │ ├── introduction.mdx # Spanish │ └── quickstart.mdx ├── fr/ │ ├── introduction.mdx # French │ └── quickstart.mdx └── de/ ├── introduction.mdx # German └── quickstart.mdx ``` Referencie as páginas na navegação usando o caminho completo, incluindo o prefixo do idioma: ```json { "language": "es", "tabs": [ { "tab": "Documentación", "groups": [ { "group": "Comenzar", "pages": ["es/introduction", "es/quickstart"] } ] } ] } ``` ## Configurações específicas do idioma Cada idioma pode ter sua própria configuração: ```json { "navigation": { "languages": [ { "language": "en", "tabs": [...] }, { "language": "es", "tabs": [...] } ] } } ``` Os banners são definidos globalmente no nível superior de `docs.json` (consulte [Banner](/pt/config/docs-json-reference#banner)), não por idioma. Um único banner é exibido em todas as páginas de todos os idiomas. ## Traduzindo rótulos da barra de navegação Os links da navegação superior e o CTA principal aceitam um objeto `labels` opcional com substituições por idioma. Quando o leitor está em uma URL com prefixo de idioma (por exemplo, `/fr/...`), a substituição correspondente é usada; caso contrário, o `label` padrão é exibido. ```json docs.json { "navbar": { "links": [ { "label": "Blog", "labels": { "fr": "Blog", "es": "Blog" }, "href": "/blog" }, { "label": "Pricing", "labels": { "fr": "Tarifs", "es": "Precios" }, "href": "/pricing" } ], "primary": { "type": "button", "label": "Dashboard", "labels": { "fr": "Tableau de bord", "es": "Panel" }, "href": "https://app.example.com" } } } ``` As strings integradas da interface (o botão **Search**, o botão **Ask AI** e o menu suspenso de abas **More**) são traduzidas automaticamente para todos os idiomas compatíveis. Não é necessário configurá-las. ## Idioma padrão O primeiro idioma no array é o padrão. Os usuários que acessarem sua documentação verão primeiro esse idioma. O seletor de idioma permite alterá-lo. ## Estrutura de URL Os prefixos de idioma aparecem nas URLs: | Idioma | URL | |----------|-----| | Inglês (padrão) | `docs.example.com/introduction` | | Espanhol | `docs.example.com/es/introduction` | | Francês | `docs.example.com/fr/introduction` | ## Traduções parciais Não é necessário traduzir todas as páginas. Se uma página não existir em determinado idioma, os usuários verão uma mensagem de fallback com um link para a versão em inglês. Para páginas que não devem ser traduzidas, como referências de API, você pode referenciar a mesma página em todos os idiomas: ```json { "language": "es", "tabs": [ { "tab": "API", "groups": [ { "group": "Endpoints", "pages": ["api/users", "api/posts"] // Same as English } ] } ] } ``` ## Traduzindo especificações OpenAPI As páginas de endpoint baseadas em OpenAPI, aquelas com uma diretiva `openapi:` no frontmatter, renderizam conteúdo de um arquivo de especificação YAML ou JSON. Para traduzir o resumo do endpoint, as descrições, as dicas de parâmetros e as descrições dos campos do esquema, forneça um arquivo de especificação específico para o idioma junto ao arquivo em inglês. ### Nomenclatura de arquivos Coloque a especificação traduzida ao lado da original, inserindo o código do idioma antes da extensão: ```bash openapi/ ├── api.yaml # English (default) ├── api.fr.yaml # French ├── api.es.yaml # Spanish └── api.zh.yaml # Simplified Chinese ``` Não é necessária nenhuma alteração de configuração ou em `docs.json`. O Jamdesk resolve a especificação correspondente no momento da renderização com base no prefixo de idioma da URL. Uma página em `/fr/api-reference/create-ticket` procura primeiro por `api.fr.yaml` e usa `api.yaml` como fallback caso nenhuma tradução exista. ### O que traduzir na especificação Traduza o texto legível por humanos. Mantenha todos os valores estruturais idênticos entre os idiomas. | Traduzir | Manter idêntico | |-----------|----------------| | `info.title`, `info.description` | versão `openapi` / `swagger`, `servers[*].url` | | `summary`, `description` de cada operação | caminhos de URL, métodos HTTP, `operationId`, `tags` | | `description` de cada parâmetro | nomes de parâmetros (`name`), nomes de campos, chaves de propriedades do esquema | | `description` de cada resposta | chaves de códigos de status (`"200"`, `"400"`, etc.) | | `requestBody.description` | valores de `enum` (`low`, `normal`, `high`), `type`, `format` | | `description` do esquema e `description` das propriedades | ponteiros `$ref`, conteúdo de `example` / `examples` | ### Comportamento de fallback Se uma página for solicitada em uma URL localizada, mas não existir uma especificação traduzida, o Jamdesk renderizará a especificação em inglês dentro do shell da página traduzida. Os usuários verão um bloco de endpoint em mais de um idioma, em vez de um erro 404. Esse comportamento corresponde ao funcionamento mais amplo das traduções parciais para páginas MDX. A visualização local da CLI `jamdesk` (`jamdesk dev`) resolve as especificações OpenAPI apenas pelo nome do arquivo. Ela ainda não aplica a busca pelo sufixo de idioma. Ao trabalhar localmente nas traduções, use a URL de visualização do Jamdesk em produção (`.jamdesk.app//...`) ou substitua temporariamente o arquivo de origem. Isso afeta apenas o desenvolvimento local; as renderizações hospedadas e de ISR selecionam corretamente a especificação traduzida. ### Removendo uma especificação específica do idioma Excluir `api..yaml` fará com que a página use a especificação em inglês no próximo processamento, sem necessidade de um novo build. Para traduzir novamente do zero, exclua o arquivo e gere-o outra vez. Nenhuma alteração em `docs.json` é necessária — a resolução da especificação é feita exclusivamente com base no nome do arquivo. ### Exemplo Origem `openapi/tickets.yaml`: ```yaml info: title: Tickets API description: Manage support tickets. paths: /tickets: post: summary: Create a ticket description: Create a new support ticket. operationId: createTicket ``` Tradução francesa `openapi/tickets.fr.yaml`: ```yaml info: title: API Tickets description: Gérez les tickets de support. paths: /tickets: post: summary: Créer un ticket description: Créer un nouveau ticket de support. operationId: createTicket ``` Observe que `/tickets`, `post` e `createTicket` permanecem idênticos. Apenas o texto descritivo é alterado. ## Fluxo de tradução Escreva primeiro sua documentação em inglês. Ela será sua fonte de verdade. Crie diretórios para cada idioma de destino (`es/`, `fr/`, etc.). Copie os arquivos em inglês para os diretórios dos idiomas e traduza-os. Mantenha os mesmos nomes de arquivo. Adicione entradas de idioma à configuração da navegação. ## Idiomas RTL Idiomas escritos da direita para a esquerda, como árabe e hebraico, são compatíveis. O Jamdesk aplica automaticamente o estilo RTL quando esses idiomas estão ativos. ## O que vem a seguir? Configure abas, grupos e a estrutura das páginas Opções completas de configuração