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 as línguas disponíveis, detecte o local do usuário e construa aplicações internacionalizadas que fornecem conteúdo em várias línguas.

Pense nisso como seu gerenciador de idiomas - em vez de codificar as línguas em seu aplicativo, você busca a lista de línguas ativas 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 à língua do dispositivo do usuário
🌐 Sites - Mostre conteúdo na língua preferida do visitante
📚 Documentação - Forneça ajuda em várias línguas
🎮 Jogos - Traduza a interface e o conteúdo

O problema de codificar línguas:

Questões:

🔄 Difícil de atualizar - É necessário reimplantar para adicionar novas línguas
🌍 Não sincronizado - As línguas do aplicativo podem diferir das línguas 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 as línguas mudam

A solução Locales:

Benefícios:

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

✨ Conceitos Chave

O que é um Locale?

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

Código da Língua - Código de língua 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 Locale - Formato combinado: language_REGION (por exemplo, en_US, ru_RU, ar_SA)

Exemplos:

Código do Locale	Língua	Região	Descrição
`en_US`	Inglês	Estados Unidos	Inglês Americano
`en_GB`	Inglês	Grã-Bretanha	Inglês Britânico
`ru_RU`	Russo	Rússia	Russo
`es_ES`	Espanhol	Espanha	Espanhol Europeu
`es_MX`	Espanhol	México	Espanhol Mexicano
`ar_SA`	Árabe	Arábia Saudita	Árabe (Arábia Saudita)
`fr_FR`	Francês	França	Francês
`de_DE`	Alemão	Alemanha	Alemão

Estrutura do Locale

Cada locale no OneEntry tem:

{
  id: 146,                      // ID único
  shortCode: 'en',              // código curto
  code: 'en_US',                // código completo
  name: 'English (USA)',        // nome
  nativeName: 'English (USA)',  // nome nativo
  isActive: true,               // está ativo
  image: null,                  // imagem
  position: 1,                  // posição
}

Por que usar o módulo Locales?

Benefício	Descrição
Suporte a múltiplas línguas	Forneça conteúdo na língua preferida do usuário
Lista de línguas dinâmica	As línguas sincronizam com a configuração do OneEntry
Detecção de Locale padrão	Identifique automaticamente a língua padrão
Filtragem de Locale ativo	Mostre apenas línguas habilitadas
Gerenciamento centralizado	Atualize línguas no painel de administração, não no código
Experiência do usuário	Permita que os usuários escolham sua língua

Casos de Uso Comuns

Caso de Uso	Descrição	Exemplo
Seletor de Língua	Menu suspenso para alternar línguas	Cabeçalho do site com bandeiras de línguas
Localização de Conteúdo	Busque conteúdo na língua do usuário	Postagens de blog em inglês ou russo
Roteamento	Estrutura de URL por língua	`/en/about`, `/ru/about`
Lógica de Fallback	Mostre a língua padrão se a tradução estiver faltando	Mostre inglês se o espanhol não estiver disponível
Preferências do Usuário	Lembre-se da escolha de língua do usuário	Salve 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:

Painel de Administração do OneEntry → Configurações → Línguas → Adicionar Língua → Selecionar 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:

Status	Significado	Quando Usar
Ativo (`isActive: true`)	Locale está habilitado e tem conteúdo	Mostrar no seletor de línguas
Inativo (`isActive: false`)	Locale está desabilitado ou sendo preparado	Ocultar dos usuários

Melhor prática: Sempre filtre por isActive ao construir seletores de línguas

Locale Padrão

Todo projeto OneEntry tem um locale padrão:

Locale padrão (isDefault: true) - A língua primária
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:

Campo	Formato	Exemplo	Usar Para
`code`	`language_REGION`	`en_US`, `ru_RU`	Identificação completa do locale
`shortCode`	`language`	`en`, `ru`	Identificação apenas da língua

📊 Tabela de Referência Rápida

Método	Descrição	Caso de Uso
getLocales()	Obter todos os locales (ativos e inativos)	Buscar línguas disponíveis

❓ Perguntas Frequentes (FAQ)

Como adiciono novas línguas 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 a língua 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 língua?

Agrupe variantes da mesma língua

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 as línguas da interface correspondam ao conteúdo disponível

🎓 Melhores Práticas

Sempre filtre locales ativos - Mostre apenas línguas habilitadas
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 língua
Valide os códigos de locale - Verifique se o locale existe antes de usar
Detecte a língua do navegador - Selecione automaticamente a língua do usuário
Agrupe por língua - Mostre variantes de língua 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 de múltiplas línguas na Plataforma OneEntry, você pode personalizar flexivelmente a interface do seu painel e gerenciar convenientemente as línguas em seu projeto. Nesta seção, você pode aprender sobre os princípios de trabalho com línguas.


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

🔗 Documentação Relacionada

Módulo de Páginas - Buscar conteúdo de página localizado
Módulo de Produtos - Gerenciar produtos em múltiplas línguas
Módulo GeneralTypes - Classificação de tipos de entidade
Módulo Admins - Usuários administradores que gerenciam locales

Introdução

🎯 O que este módulo faz?​

📖 Explicação Simples​

✨ Conceitos Chave​

O que é um Locale?​

Estrutura do Locale​

Por que usar o módulo Locales?​

Casos de Uso Comuns​

📋 O que você precisa saber​

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

Locales Ativos vs. Inativos​

Locale Padrão​

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

📊 Tabela de Referência Rápida​

❓ Perguntas Frequentes (FAQ)​

Como adiciono novas línguas ao meu projeto?​

Como defino a língua padrão?​

Devo mostrar locales inativos para os usuários?​

Como lido com traduções faltantes?​

Posso armazenar em cache os locales?​

Posso usar Locales com Next.js i18n?​

Como agrupo locales por língua?​

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

💡 Notas Importantes​

Locales são Somente Leitura​

Sempre Filtre Locales Ativos​

O Armazenamento em Cache é Recomendado​

Sincronize com os Locales de Conteúdo​

🎓 Melhores Práticas​

Definição do módulo Locales​

🔗 Documentação Relacionada​