Pular para o conteúdo principal

Introdução

Recupere os idiomas configurados em seu projeto para habilitar conteúdo multilíngue e detecção de localidade.

Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/category/languages

🎯 O que este módulo faz?​

O módulo Locales permite que você gerencie o suporte a múltiplos idiomas em seu projeto OneEntry - recupere os idiomas disponíveis, detecte a localidade do usuário e construa aplicações internacionalizadas que fornecem conteúdo em vários idiomas.

Pense nisso como seu gerenciador de idiomas - em vez de codificar idiomas no seu aplicativo, você busca a lista de idiomas ativos do OneEntry dinamicamente, permitindo que seu conteúdo se adapte automaticamente a diferentes localidades (inglês, russo, árabe, espanhol, etc.).

📖 Explicação Simples​

Em aplicações modernas, você frequentemente precisa suportar múltiplos idiomas:

  • 🌍 Sites de e-commerce - Atenda clientes em diferentes países (inglês, francês, alemão)
  • 📱 Aplicativos móveis - Adapte a interface ao idioma do dispositivo do usuário
  • 🌐 Sites - Mostre conteúdo no idioma preferido do visitante
  • 📚 Documentação - Forneça ajuda em múltiplos idiomas
  • 🎮 Jogos - Traduza a interface e o conteúdo

O problema com a codificação rígida de idiomas:

Problemas:

  • 🔄 Difícil de atualizar - É necessário reimplantar para adicionar novos idiomas
  • 🌍 Não sincronizado - Os idiomas do aplicativo podem diferir dos idiomas do CMS
  • ❌ Desajustes de tradução - O conteúdo existe no CMS, mas não no aplicativo
  • 🔧 Manutenção manual - Atualize o código toda vez que os idiomas mudarem

A solução Locales:

Benefícios:

  • 🔄 Sempre em sincronia - Os idiomas correspondem ao que está configurado no OneEntry
  • 🌍 Dinâmico - Adicione/remova idiomas sem mudanças no código
  • ✅ Validado - Mostre apenas idiomas que têm conteúdo
  • 🎯 Centralizado - Gerencie idiomas em um só lugar

✨ Conceitos Chave​

O que é uma Localidade?​

Uma localidade é uma combinação de idioma e região que determina como o conteúdo é exibido:

  • Código do Idioma - Código de idioma ISO 639-1 (por exemplo, en, ru, ar)
  • Código da Região - Código de país ISO 3166-1 (por exemplo, US, GB, RU)
  • Identificador de Localidade - Formato combinado: idioma_REGIÃO (por exemplo, en_US, ru_RU, ar_SA)

Exemplos:

Código da LocalidadeIdiomaRegiãoDescrição
en_USInglêsEstados UnidosInglês Americano
en_GBInglêsGrã-BretanhaInglês Britânico
ru_RURussoRússiaRusso
es_ESEspanholEspanhaEspanhol Europeu
es_MXEspanholMéxicoEspanhol Mexicano
ar_SAÁrabeArábia SauditaÁrabe (Arábia Saudita)
fr_FRFrancêsFrançaFrancês
de_DEAlemãoAlemanhaAlemão

Estrutura da Localidade​

Cada localidade no OneEntry tem:

{
  id: 146,                      // unique ID
  shortCode: 'en',              // short code
  code: 'en_US',                // full code
  name: 'English (USA)',        // name
  nativeName: 'English (USA)',  // native name
  isActive: true,               // is active
  image: null,                  // image
  position: 1,                  // position
}

Por que usar o módulo Locales?​

BenefícioDescrição
Suporte a múltiplos idiomasForneça conteúdo no idioma preferido do usuário
Lista de idiomas dinâmicaIdiomas sincronizados com a configuração do OneEntry
Detecção de localidade padrãoIdentifique automaticamente o idioma padrão
Filtragem de localidade ativaMostre apenas idiomas habilitados
Gerenciamento centralizadoAtualize idiomas no painel de administração, não no código
Experiência do usuárioPermita que os usuários escolham seu idioma

Casos de Uso Comuns​

Caso de UsoDescriçãoExemplo
Seletor de IdiomaMenu suspenso para alternar idiomasCabeçalho do site com bandeiras de idiomas
Localização de ConteúdoBusque conteúdo no idioma do usuárioPostagens de blog em inglês ou russo
RoteamentoEstrutura de URL por idioma/en/about, /ru/about
Lógica de FallbackMostre o idioma padrão se a tradução estiver ausenteMostre inglês se o espanhol não estiver disponível
Preferências do UsuárioLembre-se da escolha de idioma do usuárioSalve a localidade em cookies/localStorage

📋 O que você precisa saber​

As Localidades são configuradas no Painel de Administração​

Você não pode criar localidades via SDK - elas são configuradas no painel de administração do OneEntry:

OneEntry Admin Panel → Settings → Languages → Add Language → Select Locale

O SDK é para buscar informações de localidade, não para criar localidades.

Localidades Ativas vs. Inativas​

Nem todas as localidades configuradas podem estar ativas:

StatusSignificadoQuando Usar
Ativa (isActive: true)Localidade está habilitada e tem conteúdoMostrar no seletor de idiomas
Inativa (isActive: false)Localidade está desabilitada ou sendo preparadaOcultar dos usuários

Melhor prática: Sempre filtre por isActive ao construir seletores de idiomas

Localidade Padrão​

Todo projeto OneEntry tem uma localidade padrão:

  • Localidade padrão (isDefault: true) - O idioma principal
  • Usada quando nenhuma localidade é especificada
  • Fallback quando a tradução está ausente

Código da Localidade vs. Código Curto​

Cada localidade tem dois formatos de código:

CampoFormatoExemploUso Para
codeidioma_REGIÃOen_US, ru_RUIdentificação completa da localidade
shortCodeidiomaen, ruIdentificação apenas do idioma

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
getLocales()Obter todas as localidades (ativas e inativas)Buscar idiomas disponíveis

❓ Perguntas Frequentes (FAQ)​

Como adiciono novos idiomas ao meu projeto?​

Você não pode adicionar localidades via SDK. As localidades são configuradas no painel de administração do OneEntry.

Como defino o idioma padrão?​

Você não pode definir a localidade padrão via SDK. A localidade padrão é configurada no painel de administração do OneEntry:

Nota: Apenas uma localidade pode ser padrão por vez.

Devo mostrar localidades inativas para os usuários?​

Não! Sempre filtre por isActive:

Por quê? Localidades inativas podem:

  • Estar em desenvolvimento (conteúdo não pronto)
  • Estar temporariamente desabilitadas
  • Não ter traduções para todo o conteúdo

Como lido com traduções ausentes?​

Use lógica de fallback

Posso armazenar em cache localidades?​

Sim! As localidades raramente mudam, então o cache é recomendado.

Posso usar Locales com Next.js i18n?​

Sim! Integre localidades do OneEntry com Next.js.

Como agrupo localidades por idioma?​

Agrupe variantes do mesmo idioma

E se eu precisar traduzir elementos da interface (não conteúdo do CMS)?​

O módulo Locales do OneEntry é apenas para localidades de conteúdo do CMS. Para tradução da interface:

Opção 1: Use a biblioteca i18n (react-i18next, next-i18next)

Opção 2: Armazene traduções da interface no OneEntry

Crie um tipo de página "traduções" e busque strings de tradução

💡 Notas Importantes​

As Localidades são Somente Leitura​

O módulo Locales é somente leitura:

  • ✅ Buscar localidades
  • ✅ Filtrar por status ativo
  • ✅ Encontrar localidade padrão
  • ❌ Não pode criar localidades
  • ❌ Não pode atualizar localidades
  • ❌ Não pode excluir localidades

Para modificar: Use o painel de administração do OneEntry.

Sempre Filtre Localidades Ativas​

Mostre apenas localidades ativas para os usuários

Por quê? Localidades inativas podem não ter traduções completas.

O Cache é Recomendado​

As localidades raramente mudam - implemente cache

Sincronize com Localidades de Conteúdo​

Garanta que os idiomas da interface correspondam ao conteúdo disponível

🎓 Melhores Práticas​

  • Sempre filtre localidades ativas - Mostre apenas idiomas habilitados
  • Armazene localidades em cache - Elas raramente mudam, cache para desempenho
  • Use a localidade padrão como fallback - Lide com traduções ausentes
  • Salve a preferência do usuário - Lembre-se da escolha de idioma
  • Valide códigos de localidade - Verifique se a localidade existe antes de usar
  • Detecte o idioma do navegador - Selecione automaticamente o idioma do usuário
  • Agrupe por idioma - Mostre variantes de idioma de forma lógica

Definição do módulo Locales​

O módulo 'Locales' permite suporte a múltiplos idiomas no OneEntry.

Graças ao suporte a múltiplos idiomas na Plataforma OneEntry, você pode personalizar flexivelmente a interface do seu painel e gerenciar idiomas de forma conveniente em seu projeto. Nesta seção, você pode aprender sobre os princípios de trabalho com idiomas.


const { Locales } = defineOneEntry(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

🔗 Documentação Relacionada​