Introdução

Busque os idiomas configurados em seu projeto para alimentar 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ê busque os idiomas ativos configurados em seu projeto OneEntry - para que você possa construir aplicações internacionalizadas que fornecem conteúdo em vários 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 às localidades que você habilitou (inglês, russo, árabe, espanhol, etc.). Os idiomas são configurados no painel de administração do OneEntry; o SDK é somente leitura e apenas busca essas informações.

🚀 Início Rápido

Inicialize o módulo a partir de defineOneEntry:

const { Locales } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Busque as localidades ativas e leia seus campos:

// Returns only active locales (isActive: true).
const locales = await Locales.getLocales();

console.log(`${locales.length} active languages`);

locales.forEach((locale) => {
  console.log(locale.code, locale.name, locale.shortCode);
});

✨ 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 Localidade	Idioma	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 da Localidade

Cada localidade retornada por getLocales() (ILocalEntity) possui:

{
  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 (always true here)
  image: null,                  // image
  position: 1,                  // position
}

Código da Localidade vs. Código Curto

Cada localidade tem dois formatos de código:

Campo	Formato	Exemplo	Uso Para
code	idioma_REGIÃO	en_US, ru_RU	Identificação completa da localidade
shortCode	idioma	en, ru	Identificação apenas do idioma

---

📋 O que Você Precisa Saber

As localidades são configuradas no painel de administração (somente leitura)

Você não pode criar, atualizar ou excluir localidades via o 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 apenas.

O SDK retorna apenas localidades ativas

getLocales() retorna apenas os objetos de localização de idioma ativos (isActive: true). Localidades inativas configuradas no painel de administração não são retornadas, portanto, não há necessidade de filtrá-las no cliente. Cada localidade retornada ainda carrega a flag isActive (sempre true aqui), juntamente com code, shortCode, name, nativeName, image e position.

Não há um campo de localidade padrão na resposta — escolha e armazene um idioma de fallback em seu próprio aplicativo.

---

📊 Tabela de Referência Rápida

Método	Descrição	Caso de Uso
getLocales()	Obter todas as localidades ativas	Buscar idiomas disponíveis

---

❓ Perguntas Comuns (FAQ)

Como adiciono novos idiomas ao meu projeto?

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

---

O getLocales() retorna idiomas inativos?

Não. O SDK retorna apenas localidades ativas (isActive: true). Idiomas desativados no painel de administração não estão incluídos na resposta.

---

Posso armazenar em cache as localidades?

Sim. As localidades raramente mudam, portanto, é recomendável armazenar o resultado em cache para desempenho.

---

Como lido com traduções ausentes?

Escolha um idioma de fallback em seu aplicativo e recorra a ele quando o conteúdo estiver ausente para a localidade solicitada — getLocales() não inclui um campo de localidade padrão.

---

🎓 Melhores Práticas

• Confie na lista ativa - O SDK já retorna apenas localidades habilitadas, portanto, não é necessário filtrá-las no lado do cliente.
• Armazene em cache as localidades - Elas raramente mudam; armazene o resultado em cache para desempenho.
• Escolha seu próprio idioma de fallback - Não há um campo de localidade padrão; trate traduções ausentes em seu aplicativo.
• Combine code e shortCode - Use code (en_US) para identificação completa e shortCode (en) para lógica apenas de idioma.

---

🔗 Documentação Relacionada

• Módulo de Páginas - Buscar conteúdo de página localizado
• Módulo de Produtos - Gerenciar produtos multilíngues
• Módulo GeneralTypes - Classificação de tipo de entidade
• Módulo Admins - Usuários administradores que gerenciam localidades

---