Administrando traduções

Administrar traduções sempre foi uma tarefa tediosa – mas compartilhá-las através de diferentes plataformas pode ser um pesadelo ainda maior.

Na Hypefactors nós temos um back-end PHP, via Laravel, e nossos aplicativos front-end são apps de página única (SPA’s), feitos com Vue.js. Por causa disso, tivemos que encontrar uma forma de compartilhar traduções e palavras-chave através de 3 aplicativos e 1 back-end. 

Depois de revisar uma longa lista de vários serviços com vantagens competitivas, decidimos usar Lokalise.com. Seu conjunto de recursos e estrutura de preços é o mais adequado às nossas necessidades, já que com ele podemos criar um projeto que compartilha traduções através das nossas várias plataformas e também oferece acesso otimizado para aos tradutores. 

Como isto funciona para cada plataforma?

Vamos começar explicando a estrutura de arquivos para cada plataforma. 

Laravel

O Laravel encoraja programadores a dividir suas traduções em pequenos arquivos, cada um deles sendo nomeado da mesma forma que o segmento que está sendo traduzido. Por exemplo: o arquivo ling/pt/email/registro/novos_usuarios.php conteria todas as traduções de e-mails que um novo usuário recebe. Saiba mais em Laravel Localisation.

Isso faz com que a manutenção das traduções seja fácil, desde que você seja organizado com seu sistema de nomeação de arquivos. 

Um potencial problema com esse método é que você poderia ter códigos de conversão com o mesmo nome, mas em diferentes pastas. A maior parte dos administradores de traduções como o Laravel só reconhece códigos de conversão, e ter múltiplos deles faria com que apenas o  último a ser registrado seria o único reconhecido como válido. 

Por sorte, a Lokalise possui uma ferramenta chamada Diferenciar códigos por pasta, que faz exatamente isso – é só clicar em “Ativar para diferenciar códigos semelhantes em pastas diferentes quando eles forem importados”. 

Prós

  • Fácil de navegar
  • Reduz conflitos
  • Faz com que seja mas fácil administrar informações na base de dados que podem ser traduzidas 

Contras

  • Muitos arquivos. Isso pode fazer com que seja mais difícil sincronizar com a Lokalise

Vue

Nossos aplicativos Vue utilizam uma biblioteca chamada Vue-i18n que é a biblioteca i18n mais popular no ecossistema Vue. 

Porém, de acordo com o padrão, essa biblioteca oferece duas formas de arquivar traduções. Na forma de um arquivo en.json ou utilizando a tag <lang> dentro do seus componentes .vue.

Nós escolhemos o método do arquivo en.json ao invés da <tag>, já que é muito mais fácil fazer só o upload de arquivos en.json do que ter que criar funcionalidade depois de extrair chaves de cada arquivo .vue. 

Você também tem que escolher entre uma estrutura simples ou um objeto  deeply nested  JSON para armazenar as suas traduções. Nós optamos por utilizar a árvore-em rede, pois pareceu mais simples examinar traduções desta forma e transformá-las em componentes se necessário. 

Prós

  • Nós podemos facilmente fazer upload de arquivos originais de tradução para o Lokalise.
  • Nós podemos facilmente sincronizar traduções do Lokalise para cada linguagem
  • É fácil encontrar traduções, elas estão todas em um arquivo só.
  • É fácil compartilhar as traduções através de diferentes componentes, já que todos os componentes têm acessos as traduções. 
  • Todas as chaves para uma linguagem já estão carregadas, garantindo que o texto será corretamente exibido durante a navegação. 

Contras

  • Arquivos podem ficar muito grandes e difíceis de navegar 
  • Conflitos de unificação podem ocorrer, se as coisas acabarem se deslocando.
  • Enquanto aplicativos crescem, o número traduções também aumenta, fazendo com que cada arquivo de tradução seja mais pesado, ou seja, mais devagar para carregar da primeira vez.

Como você pode perceber, não existe nenhuma solução perfeita – sacrifícios sempre tem que ser feitos aqui e ali. 

Alguns dos problemas que tivemos que resolver:

  • Como armazenar de forma cruzada todas as traduções?
  • Como compartilhar cadeias entre diferentes apps?
  • Como sincronizar e fazer o download das traduções facilmente?
  • Como sincronizar e  fazer o upload das traduções facilmente?
  • Como escolher que formato utilizar para exportar? 
  • Como reduzir duplicações entre diferentes traduções?
  • Como atualizar via Lazy Load a linguagem das atuais cadeias de linguagem?
  • Como administrar a eliminação/atualização/mudança de uma cadeia de linguagem de fonte?
  • Como administrar mudanças entre diferentes filiais?

Como armazenar todas as traduções?

Para conseguir fazer isso, nós usamos tags.

Nós começamos com apenas um projeto do Lokalise para o back-end, e as três apps. Quando fazendo o upload,  habilitamos uma função chamada Tagging, que nos permite colocar uma série de tags nas cadeias já adicionadas. 

Por exemplo:

Para a app Hypefactors, nós usamos a tag “app”. Para Hype.news, nós usamos “hypenews”. Para a API, nós usamos “hypefactors-api”, e por aí vai.

Desta forma é muito fácil fazer download das traduções por plataforma quando você precisar. 

Como compartilhar cadeias entre diferentes apps. 

Nós utilizamos as tags para identificar quando temos uma tradução que deve ser compartilhada entre diferentes apps, e nós atribuímos uma tag compartilhada entre as apps para esta tradução. Quando estivermos sincronizando e fazendo o download, ela será baixada junto com traduções específicas para cada plataforma. Isso quer dizer que cada app requer tanto sua própria tag quanto a sua tag compartilhada. 

Como sincronizar e fazer o download das traduções facilmente.

Conseguimos fazer isso usando o CLI da Lokalise. Nós temos apenas alguns comandos que rodamos para fazer o download de todas as traduções para uma plataforma. 

Abaixo está o comando que usamos para o API:

lokalise --token {$TOKEN} export {$ID} --type php  --unzip_to resources/lang --use_original 1 --no_language_folders 1 --export_sort first_added --include_tags hypefactors-api --export_empty skip

Como sincronizar e fazer o upload das traduções facilmente. 

Atualmente, sincronizamos as traduções manualmente. Arrastamos cada arquivo fonte de tradução das apps e soltamos ele diretamente no Lookalise, na pasta fonte de traduções do API, atribuindo as tags corretas antes de processar tudo (isto dá por volta de 4-5 arquivos, no máximo).

Até agora, esta foi a melhor forma de efetuar este processo, mesmo que alguma quantidade de trabalho manual esteja envolvido,  já que podemos monitorar a quantidade de novas traduções sendo adicionadas e atualizadas.

Nós também poderíamos utilizar o CLI para fazer o upload e identificação automáticos, mas isso é uma tarefa para um outro dia. 

Como administrar a eliminação/atualização/mudança de cadeias de linguagem fonte. 

Você deve ter apenas uma fonte da verdade. Todos os seus tradutores irão utilizar o Lokalise, já que esse é o propósito dele. Mas não pode ser esperado que você adicione traduções lá de primeira, assim que você estiver programando. 

É exatamente por isso que nós adicionamos novas cadeias aos nossos arquivos de origem, como por exemplo en.json , e então fazemos upload deles para o Lokalise sem habilitar a ferramenta atualizar. Nós podemos ver quais cadeias foram adicionadas recentemente, e aí as sincronizamos para obter as novas traduções. Nós fazemos este processo para cada uma das plataformas. 

Potenciais dificuldades

  1. Colisão entre cadeias de origem local e remota

Mudanças de traduções de origem devem ser feitas no Lokalise. O Lokalise permite que você automaticamente atualize cadeias alteradas de cadeias de origens durante o upload, o que irá substituir quaisquer cadeia existente que seja diferente da sua atualização. 

Alterar os arquivos de origem diretamente pode resultar em uma colisão com cadeias potencialmente atualizadas no Lokalise, se você ainda não atualizou os seus arquivos locais. 

Exemplo: A administração atualiza a formulação do texto, mas você ainda não fez o download da última versão. Você faz o update do seu arquivo, e sobrescreve a atualização durante o seu upload para o Lokalise. A administração perde as edições que fizeram. 

É por isso que encorajamos programadores a sincronizar e fazer download das traduções antes de fazer quaisquer mudanças nos seus arquivos locais, e nunca automaticamente sobrescrever cadeias no Lokalise.

Como escolher que formato usar para exportar

Isso é feito através dos parâmetros UI ou CLI. O Lookalise não salva os arquivos que você importa – ele analisa as traduções e oferece algumas opções de formas para exportar. 

Nós simplesmente escolhemos exportar para série PHP Laravel e aí selecionamos  “Usar nomes de arquivos previamente atribuídos com o directory prefix à seguir”. Isso irá exportar todos os arquivos com a mesma estrutura que havíamos usado para fazer o upload delas. 

Os parâmetros CLI são:

--type php --use_original 1 --no_language_folders 1

Como reduzir o número de duplicações em diferentes plataformas

Utilizamos uma ferramenta chamada “Localizador de Duplicações”, e escaneamos em busca de cadeias de origem idênticas. Com isso, podemos atribuir uma cadeia de origem mestre, que o resto simplesmente usará para copiar a tradução.  É uma ótima função que pode te ajudar a economizar um muito dinheiro em tradutores. More on the feature.

Como “Lazy Load” as cadeias de linguagem atuais.

Ao invés de carregar todas as traduções no momento da inicialização, nós carregamos apenas as em Inglês. Uma vez que a app está inicializada, nós conseguimos detectar a linguagem que está aplicada, e conseguimos sincronizar e carregar um arquivo de tradução. Normalmente isso demora apenas milisegundos, e o usuário nem percebe. 

Temos Inglês carregado como padrão. Desta forma, caso a conexão esteja devagar, não teremos um caso de cadeias path.to.key.of.translation espalhadas por todo o lugar na tela.

Você pode descobrir mais sobre como fazer isso com o Vue aqui: “Adicione i18n e administre traduções em um site gerido por Vue.js”.

Como administrar mudanças entre diferentes filiais

Isso não é compatível com a plataforma deles no momento, mas está em desenvolvimento. Então decidimos apenas atualizar as traduções novas ou atualizadas para uma filial, após o QA, logo antes de uma distribuição. Isto poderia atrasar a distribuição até as traduções estarem finalizadas.

Considerações finais

Localização nunca foi uma tarefa fácil. Como você pode ver, existem múltiplas coisas que podem dar errado, múltiplas coisas que precisam ser levadas em consideração quando adicionando ou atualizando traduções. Plataformas como o Lokalise fazem com que a interação entre programadores e tradutores um pouco mais fácil.