Central de Ajuda Quaza Provedores

Traduções do Sistema Quaza Visão geral O sistema Quaza utiliza o gettext para internacionalização (i18n).

Visão geral

O sistema Quaza utiliza o gettext para internacionalização (i18n). Todo texto visível para o usuário final deve ser marcado com a função _() no código PHP, permitindo que o sistema exiba o conteúdo no idioma configurado.

Idiomas suportados

Idiomas base

Variações do espanhol

As variações contêm apenas os termos que diferem do espanhol base. Na prática, são termos de documentos fiscais e de identificação, que mudam de país para país.

Nota: O es_PY é a referência principal — os termos foram validados diretamente pelo cliente do Paraguai.

Para desenvolvedores

Como marcar textos para tradução

Todo texto exibido em tela (labels, mensagens, exceções, títulos de popup, etc.) deve estar dentro de _():

// Labels e mensagens
$msg = _("Operação realizada com sucesso.");
// Exceções
throw new \UserException(_("Campo obrigatório!"));
// Colunas de model
$columns['nome'] = new Column(_('Nome'), 'nome', Column::TYPE_VARCHAR, 255);
// Botões e componentes visuais
$btn = new \View\Ext\Button('', 'check', _('Confirmar'), 'salvar', 'success');

Exceção: arquivos dentro do diretório py/ não seguem essa regra.

O que NÃO marcar com _()

• Nomes de variáveis, classes ou métodos
• Valores de configuração internos
• Logs técnicos (ex: \Log::debug())
• Queries SQL
• Chaves de array internas

Ao criar strings novas

• Use frases completas, não concatene pedaços traduzíveis
• Use %s, %d para valores dinâmicos (compatível com sprintf)
• Mantenha o texto em português dentro do _()

Como gerar as traduções

Da raiz do projeto, execute:

sh locale/gerar.sh

Esse script faz tudo automaticamente:

1. Extrai todas as strings marcadas com _() dos arquivos PHP
   • Exclui: storage/, vendor/, testes/, locale/
2. Combina as variações do espanhol com o es base (via msgcat --use-first)
3. Compila os arquivos .mo para todos os idiomas

O script pode ser executado da raiz (sh locale/gerar.sh) ou de dentro da pasta locale (sh gerar.sh).

Como traduzir strings novas

Após rodar o gerar.sh, strings novas aparecem nos .po com msgstr "" (vazio).

Passo a passo:

1. Abra locale/en_US/LC_MESSAGES/quaza.po e traduza para inglês
2. Abra locale/es/LC_MESSAGES/quaza.po e traduza para espanhol genérico
3. Se a string contém termos que mudam por país (CPF, CNPJ, CEP, etc.), adicione nos .po das variações — caso contrário, o es base já cobre
4. Rode sh locale/gerar.sh novamente para recompilar

Exemplo de entrada no .po:

msgid "Campo obrigatório!"
msgstr "Required field!"

Estrutura de arquivos

locale/
├── gerar.sh                          # Script único (extrai + combina + compila)
├── gerarcombined.sh                  # Combina variações (chamado pelo gerar.sh)
├── gerarmo.sh                        # Compila .mo (chamado pelo gerar.sh)
├── pt_BR/LC_MESSAGES/
│   ├── quaza.po                      # Strings originais (msgstr geralmente vazio)
│   └── quaza.mo                      # Compilado
├── en_US/LC_MESSAGES/
│   ├── quaza.po                      # Traduções pt_BR → inglês
│   └── quaza.mo
├── es/LC_MESSAGES/
│   ├── quaza.po                      # Traduções pt_BR → espanhol (base)
│   └── quaza.mo
├── es_PY/LC_MESSAGES/
│   ├── quaza.po                      # Apenas termos específicos do Paraguai
│   ├── quaza_combined.po             # Gerado: es_PY + es base combinados
│   └── quaza.mo                      # Compilado a partir do combined
└── es_AR, es_BO, es_MX, es_UY/      # Mesma estrutura que es_PY

Como a combinação funciona

O gerarcombined.sh usa msgcat --use-first para mesclar:

es_PY/quaza.po (termos específicos) + es/quaza.po (base) = es_PY/quaza_combined.po

O --use-first dá prioridade ao primeiro arquivo. Então se es_PY tem uma tradução para "CPF/CNPJ" → "RUC", ela prevalece sobre o que estiver no es base.

Adicionar um novo país

1. Criar o diretório: locale/es_XX/LC_MESSAGES/
2. Criar o quaza.po com header e apenas os termos específicos do país
3. Adicionar o código do país na variável IDIOMAS_VARIACAO do locale/gerar.sh
4. Rodar sh locale/gerar.sh

Para o suporte

Como funciona a tradução para o cliente

O idioma do sistema é configurado por empresa/provedor. Quando o usuário acessa o sistema, todos os textos da interface são exibidos no idioma configurado.

Problemas comuns

Texto aparece em português mesmo com idioma configurado

O texto provavelmente não está marcado com _() no código. Reportar para o desenvolvimento indicando:

• Qual tela/página
• Qual texto está sem tradução
• Qual idioma esperado

Tradução aparece errada ou com termo incorreto

Os termos de documentos (CPF, CNPJ, CEP, etc.) variam por país. Se um cliente reportar que o termo está errado:

• Verificar se o país do cliente está usando a variação correta (ex: es_PY para Paraguai)
• Se o termo está na variação mas incorreto, reportar para ajuste no .po correspondente

Texto aparece como "Nota de crédito" em vez do termo local

Se o texto é genérico (não muda por país), ele vem do es base. Se o cliente quer um termo diferente do padrão, será necessário adicionar no .po da variação do país.

Referência rápida de termos por país

Dependências

RedHat/CentOS

yum install gettext
yum install php-php-gettext

Debian/Ubuntu

apt install gettext
apt install php-gettext

Glossário

Pegadinhas frequentes

FAQ

Quem pode acessar essa funcionalidade?

Depende da permissão do usuário. Confira com o administrador do Quaza se você não vê a opção.

O que fazer se aparecer um erro?

Anote a mensagem completa, screenshot, e abra um chamado no suporte do Quaza com esses dados.

Esta funcionalidade tem versão para cliente final?

Algumas funcionalidades têm Portal do Cliente. Verifique no módulo Portal .

Posso integrar via API?

Sim — a maioria das funcionalidades do Quaza expõe endpoints REST. Consulte a documentação técnica.

Quaza tem treinamento oficial?

Sim — equipe de suporte oferece sessões de onboarding sob agendamento.

Ciclo completo da operação

Boas práticas operacionais

Para tirar o máximo desta funcionalidade, observe os pontos abaixo. São práticas que provedores experientes adotam para evitar erros recorrentes e maximizar valor extraído do Quaza.

Antes de operar

• Confirme permissão de acesso: nem todo operador tem permissão para todas as funcionalidades. Verifique com o administrador do Quaza se algo não aparece como esperado. Permissões são vinculadas a papéis (operador, supervisor, admin).
• Cadastros pré-requisitos completos: muitas funcionalidades dependem de outros cadastros estarem completos antes. Por exemplo, antes de criar um contrato você precisa ter o cliente cadastrado, plano de vendas configurado, e regras de cobrança definidas.
• Treine pelo menos 2 operadores: redundância previne paralisação por ausência. Funcionário pode sair, ficar doente, ter dia ruim. Mantenha conhecimento distribuído entre múltiplas pessoas.
• Documente procedimentos internos: crie checklist próprio para operações recorrentes. Quem opera amanhã agradece — especialmente se for funcionário novo.

Durante a operação

• Documente decisões não óbvias: se você ajustou algo de forma diferente do default, anote o porquê. Próximo operador agradece e evita refazer análise.
• Operações em massa pedem cuidado: antes de aplicar a 100+ registros, teste com 5 e revise resultado completo. Se possível, exporte CSV antes para ter como rollback.
• Backup antes de mudanças grandes: cancelar/desfazer pode não ser possível em todas as ações. Em dúvida, faça export ou imprima tela antes.
• Comunique alterações: mudanças que impactam outras equipes (atendimento, financeiro) devem ser anunciadas com antecedência. Surpresa gera retrabalho.

Acompanhamento e revisão

• Revisão semanal de 30 minutos: dedique tempo regular para revisar o que rodou, falhou, ficou pendente neste módulo. Anomalia detectada cedo custa 10x menos que descoberta tarde.
• Defina KPIs próprios: 2-3 indicadores que medem saúde da operação. Acompanhe tendências, não só valores absolutos. Variação maior que 20% merece investigação.
• Auditoria mensal: revise sample de operações do mês passado. Use logs para confirmar que tudo aconteceu como esperado, sem desvios silenciosos.
• Compare com período anterior: "Vendi R$ 100k" — é bom? Compare com mês anterior, mesmo mês ano passado. Contexto importa mais que número absoluto.

Resolução de problemas

• Anote a mensagem de erro completa: copie o texto exato. Captura de tela ajuda. Anote quais passos levaram ao problema — facilita diagnóstico.
• Tente reproduzir em ambiente de teste: se possível, simule o erro com dado dummy antes de pedir suporte. Isso acelera resolução.
• Procure no histórico: provavelmente alguém já viu erro similar. Veja log de auditoria para entender o que mudou recentemente.
• Abra chamado bem documentado: equipe de suporte do Quaza resolve mais rápido com contexto: o que esperava, o que aconteceu, frequência, screenshots.

Indicadores típicos a acompanhar

Cada provedor define seus próprios indicadores, mas alguns são quase universais para qualquer operação no Quaza:

• Volume mensal processado (registros/transações/eventos)
• Taxa de erro (% de operações que falharam)
• Tempo médio de processamento
• Cobertura (% da carteira atendida pela funcionalidade)
• Satisfação operacional (feedback da equipe que usa)

Compare valores atuais com média dos últimos 3 meses. Variação maior que 20% em qualquer direção merece investigação — pode ser melhoria sustentável ou degradação silenciosa.

Recursos relacionados no Quaza

Este recurso se conecta com outros módulos do sistema. Conhecer essas conexões ajuda no troubleshooting e em decisões operacionais:

• Cadastro de cliente — base de tudo no Quaza. Cliente bem cadastrado evita problemas downstream.
• Plano de Contas — onde o impacto financeiro é classificado contabilmente.
• Logs de auditoria — histórico de quem fez o quê e quando, essencial para diagnóstico.
• Permissões e papéis — definem quem pode operar o quê.
• Tarefas crontab — automações que tocam neste recurso periodicamente.

Referência rápida

Atalhos e shortcuts para operação eficiente:

• Busca avançada: use filtros de data, status, responsável para reduzir lista. Filtro padrão pode esconder registros antigos.
• Exportação: a maioria das listas exporta para CSV/Excel. Útil para análise externa ou backup pré-mudança.
• Histórico: cada registro tem timeline de modificações. Acesse via botão "Histórico" ou aba lateral.
• Atalhos de teclado: Ctrl+F (busca), Ctrl+S (salvar), Esc (cancelar) na maioria das telas.
• Permissão restrita: se botão estiver cinza, é falta de permissão — não bug.