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)