Pular para o conteúdo principal

Introdução

🎯 O que este módulo faz?​

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

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

📖 Explicação Simples​

Em aplicações modernas, você frequentemente precisa suportar múltiplas línguas:

  • 🌍 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últiplas línguas
  • 🎮 Jogos - Traduza a interface e o conteúdo

O problema de codificar 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 é um Locale?​

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

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

Exemplos:

Código do LocaleIdiomaRegiã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 do Locale​

Cada locale 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últiplas línguasSirva conteúdo no idioma preferido do usuário
Lista de idiomas dinâmicaIdiomas sincronizam com a configuração do OneEntry
Detecção de locale padrãoIdentifique automaticamente o idioma padrão
Filtragem de locale ativoMostre 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 faltandoMostre inglês se o espanhol não estiver disponível
Preferências do UsuárioLembre-se da escolha de idioma do usuárioSalve o locale em cookies/localStorage

📋 O que você precisa saber​

Locales são configurados no Painel de Administração​

Você não pode criar locales via SDK - eles são configurados no painel de administração do OneEntry:

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

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

Locales Ativos vs. Inativos​

Nem todos os locales configurados podem estar ativos:

StatusSignificadoQuando Usar
Ativo (isActive: true)Locale está habilitado e tem conteúdoMostrar no seletor de idiomas
Inativo (isActive: false)Locale está desabilitado ou sendo preparadoOcultar dos usuários

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

Locale Padrão​

Cada projeto OneEntry tem um locale padrão:

  • Locale padrão (isDefault: true) - O idioma principal
  • Usado quando nenhum locale é especificado
  • Fallback quando a tradução está faltando

Código do Locale vs. Código Curto​

Cada locale tem dois formatos de código:

CampoFormatoExemploUsado Para
codeidioma_REGIÃOen_US, ru_RUIdentificação completa do locale
shortCodeidiomaen, ruIdentificação apenas do idioma

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
getLocales()Obter todos os locales (ativos e inativos)Buscar idiomas disponíveis

❓ Perguntas Frequentes (FAQ)​

Como adiciono novos idiomas ao meu projeto?​

Você não pode adicionar locales via SDK. Os locales são configurados no painel de administração do OneEntry.

Como defino o idioma padrão?​

Você não pode definir o locale padrão via SDK. O locale padrão é configurado no Painel de Administração do OneEntry:

Nota: Apenas um locale pode ser padrão por vez.

Devo mostrar locales inativos para os usuários?​

Não! Sempre filtre por isActive:

Por quê? Locales inativos podem:

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

Como lido com traduções faltantes?​

Use lógica de fallback

Posso armazenar em cache os locales?​

Sim! Os locales raramente mudam, então o armazenamento em cache é recomendado.

Posso usar Locales com Next.js i18n?​

Sim! Integre os locales do OneEntry com o Next.js.

Como agrupo locales 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 locales 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​

Locales são Somente Leitura​

O módulo Locales é somente leitura:

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

Para modificar: Use o Painel de Administração do OneEntry.

Sempre Filtre Locales Ativos​

Mostre apenas locales ativos para os usuários

Por quê? Locales inativos podem não ter traduções completas.

O Armazenamento em Cache é Recomendado​

Locales raramente mudam - implemente o armazenamento em cache

Sincronize com os Locales de Conteúdo​

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

🎓 Melhores Práticas​

  • Sempre filtre locales ativos - Mostre apenas idiomas habilitados
  • Armazene em cache os locales - Eles raramente mudam, armazene em cache para desempenho
  • Use o locale padrão como fallback - Lide com traduções faltantes
  • Salve a preferência do usuário - Lembre-se da escolha de idioma
  • Valide os códigos de locale - Verifique se o locale 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

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

Definição do módulo Locales​

O módulo 'Locales' permite suporte a múltiplas línguas no OneEntry.

Graças ao suporte a múltiplas línguas 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​