Suporte multilíngue

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.

Configuração

Coloque sua navegação dentro de um array languages, com cada idioma contendo sua própria estrutura de navegação:

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

Estrutura de diretórios

Organize o conteúdo traduzido em diretórios com o prefixo do idioma:

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:

{
  "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:

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "tabs": [...]
      },
      {
        "language": "es",
        "tabs": [...]
      }
    ]
  }
}

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.

{
  "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:

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:

{
  "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:

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.

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.

Removendo uma especificação específica do idioma

Excluir api.<lang>.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:

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:

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

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?