Pular para o conteúdo principal

Estrutura de Traduções

O Nerdify utiliza arquivos YAML para internacionalização (i18n). As traduções controlam labels, placeholders, mensagens e textos exibidos na interface.


Estrutura de Arquivos

Os arquivos de tradução ficam em:

config/locales/{locale}/api/v1/{path}/{controller}/{action}.yml

Exemplo:

config/locales/pt-BR/api/v1/platform/modules/customers/customers/show.yml

A estrutura do caminho deve corresponder ao i18n_path do controller.


Estrutura Básica do YAML

---
pt-BR:
api/v1/platform/modules/customers/customers:
show:
title: Sobre o cliente
favicon: favicon.ico
meta_description: ''
keywords: ''
toast:
destroy: 'Cliente excluído com sucesso'
create: 'Cliente criado com sucesso'
update: 'Cliente atualizado com sucesso'
components:
# Componentes e campos aqui

Tradução de Componentes

Títulos e Headers

components:
# Título principal da página
customer_show:
name: Sobre o cliente

# Componente de título (h1)
customer_show_title:
name: Sobre o cliente

# Texto de ajuda/subtítulo
customer_show_help:
name: Visualize o cadastro e histórico do cliente

Campos de Formulário

components:
name:
name: Nome
placeholder: Digite o nome completo

email:
name: E-mail
placeholder: nome@email.com

phone:
name: Telefone
placeholder: (00) 99999-9999

birth_date:
name: Data de nascimento

Campos com Seleção (inclusion)

Para campos select, radio ou checkbox com opções definidas:

No Model (Ruby)

field :status, type: :select, inclusion: %w[active inactive pending]
field :gender, type: :radio, inclusion: %w[male female other]

Na Tradução (YAML)

components:
status:
name: Status
placeholder: Selecione o status
inclusion:
active:
label: Ativo
value: active
id: active
inactive:
label: Inativo
value: inactive
id: inactive
pending:
label: Pendente
value: pending
id: pending

gender:
name: Gênero
inclusion:
male:
label: Masculino
value: male
id: male
female:
label: Feminino
value: female
id: female
other:
label: Outro
value: other
id: other

Tradução de Tabs

Tabs são agrupados em fieldsets com a opção tab:. A tradução usa a chave tabs_{nome_do_fieldset_pai}.

No Model (Ruby)

fieldset :customer, size: 12 do
fieldset :about, tab: :about, size: 12 do
# campos
end

fieldset :pets, tab: :pets, size: 12 do
# campos
end

fieldset :sales, tab: :sales, size: 12 do
# campos
end
end

Na Tradução (YAML)

components:
tabs_customer:
inclusion:
about:
label: Cadastro
pets:
label: Pets
sales:
label: Vendas

Importante: A chave é tabs_{fieldset_pai}, não o nome do tab individual.


Tradução de Actions

Actions (botões) também precisam de tradução:

components:
# Botão de editar
edit_customer:
name: Editar
icon: edit

# Botão de excluir com confirmação
destroy_customer:
name: Excluir
icon: delete
confirm: Tem certeza que deseja excluir? Esta ação é irreversível.

# Botão de nova venda
new_sale_customer:
name: Nova venda
icon: add

Mensagens Toast

Defina mensagens de sucesso e erro:

toast:
create: 'Registro criado com sucesso'
update: 'Registro atualizado com sucesso'
destroy: 'Registro excluído com sucesso'

Tooltips

Para campos com tooltip: true:

components:
ltv:
name: LTV
tooltip: Lifetime Value - valor total gasto pelo cliente

average_ticket:
name: Ticket Médio
tooltip: Valor médio por compra

Exemplo Completo

---
pt-BR:
api/v1/platform/modules/customers/customers:
show:
title: Sobre o cliente
favicon: favicon.ico
meta_description: ''
keywords: ''
toast:
destroy: 'Cliente excluído com sucesso'
update: 'Cliente atualizado com sucesso'
components:
# Títulos
customer_show:
name: Sobre o cliente
customer_show_title:
name: Sobre o cliente
customer_show_help:
name: Visualize o cadastro, histórico e indicadores do cliente

# Actions
edit_customer:
name: Editar
icon: edit
destroy_customer:
name: Excluir
icon: delete
confirm: Tem certeza que deseja excluir este cliente?

# Campos
name:
name: Nome
placeholder: Digite o nome do cliente
email:
name: E-mail
placeholder: nome@email.com
phone:
name: Telefone
placeholder: (00) 99999-9999
whatsapp:
name: WhatsApp
placeholder: (00) 99999-9999
birth_date:
name: Data de nascimento
cpf_or_cnpj:
name: CPF/CNPJ
placeholder: 123.456.789-10

# Campo select com inclusion
gender:
name: Gênero
placeholder: Selecione
inclusion:
male:
label: Masculino
value: male
id: male
female:
label: Feminino
value: female
id: female
other:
label: Outro
value: other
id: other

type:
name: Tipo de cliente
inclusion:
retail:
label: Varejo
value: retail
id: retail
wholesale:
label: Atacado
value: wholesale
id: wholesale

# Indicadores
ltv:
name: LTV
tooltip: Valor total gasto pelo cliente
average_ticket:
name: Ticket Médio
tooltip: Valor médio por compra
sales_quantity:
name: Total de vendas

# Tabs
tabs_customer:
inclusion:
activity:
label: Histórico
about:
label: Cadastro
pets:
label: Pets
addresses:
label: Endereços
sales:
label: Vendas

Convenções de Nomenclatura

Títulos de Página

Sempre inclua ambas as variações para garantir compatibilidade:

# Padrão {recurso}_{action}
customer_show:
name: Sobre o cliente
customer_show_title:
name: Sobre o cliente
customer_show_help:
name: Subtítulo descritivo

# Padrão {action}_{recurso} (algumas páginas usam)
show_customer:
name: Sobre o cliente

Fieldsets

customer_form:
name: Dados do cliente
icon: person

address_form:
name: Endereço
icon: location_on

Embeds

customer_pets:
name: Pets do cliente

customer_sales:
name: Vendas

Dicas de Organização

Estrutura Recomendada

components:
# 1. Títulos primeiro
{recurso}_{action}:
{recurso}_{action}_title:
{recurso}_{action}_help:

# 2. Actions
edit_{recurso}:
destroy_{recurso}:
new_{recurso}:

# 3. Tabs (se houver)
tabs_{fieldset}:

# 4. Fieldsets
{fieldset_name}:

# 5. Campos (em ordem de aparição)
name:
email:
phone:
# ...

Boas Práticas

Faça

  • Mantenha traduções consistentes em todo o sistema
  • Use placeholders descritivos que ajudem o usuário
  • Forneça tooltips para campos não óbvios
  • Inclua mensagens de confirmação para ações destrutivas

Evite

  • Traduzir valores técnicos (IDs, chaves de API)
  • Mensagens genéricas como "Erro" ou "Inválido"
  • Duplicar traduções - use referências YAML quando possível
  • Deixar campos sem tradução (aparecerão como chaves)