Suporte multilíngue

Se 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 troquem de idioma usando um menu suspenso na barra superior.

Configuração

Envolva sua navegação em 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 os rótulos da barra de navegação

Os links da navegação superior e o CTA principal aceitam um objeto opcional labels com substituições por idioma. Quando o leitor está em uma URL com prefixo de idioma, como /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, como 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 do array é o padrão. Os usuários que acessarem sua documentação verão primeiro esse idioma. O seletor de idioma permite que eles troquem de idioma.

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 um 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 a referência 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 orientadas por OpenAPI, que contêm uma diretiva openapi: no frontmatter, renderizam o 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.

Nome do arquivo

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 de 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 api.fr.yaml e usa api.yaml como fallback se nenhuma tradução existir.

O que traduzir na especificação

Traduza o texto legível pelos usuários. Mantenha todos os valores estruturais idênticos entre os idiomas.

Comportamento de fallback

Se uma página for solicitada por uma URL localizada, mas não existir uma especificação traduzida, o Jamdesk renderizará a especificação em inglês dentro da estrutura da página traduzida. Os usuários verão um bloco de endpoint em idiomas mistos em vez de um erro 404. Isso corresponde ao comportamento geral de traduções parciais para páginas MDX.

Removendo uma especificação específica do idioma

Excluir api.<lang>.yaml faz com que a página use a especificação em inglês no próximo carregamento, sem exigir um novo build. Para traduzir novamente do zero, exclua o arquivo e gere-o outra vez. Não é necessária nenhuma alteração em docs.json: a resolução da especificação é baseada exclusivamente 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 é 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 estilos RTL quando esses idiomas estão ativos.

O que vem a seguir?