CSV

Traduza uma tabela CSV com uma coluna por idioma em um único arquivo e uma coluna à sua escolha como chave.

Uma tabela de tradução CSV reúne o texto de origem e todas as traduções em um único arquivo: uma linha por mensagem, uma coluna por idioma. O manipulador de arquivos csv preenche as células dos idiomas de destino nesse arquivo e grava o resultado no caminho de origem. Apenas as células dos idiomas de destino são gravadas, e uma coluna é adicionada quando um idioma ainda não tem uma, conforme descrito em Quais linhas são traduzidas. As demais colunas, a ordem das linhas, o uso de aspas e as terminações de linha permanecem como estavam. A marca de ordem de bytes UTF-8 no início do arquivo não é preservada: o arquivo é gravado sem ela. Por isso, se o aplicativo de planilhas depender dessa marca para detectar UTF-8, pode ser necessário importar o arquivo como UTF-8.

Organize a tabela #

A primeira linha que não está vazia nem contém apenas espaços em branco é o cabeçalho. Uma coluna contém a chave que identifica cada linha, outra contém o texto de origem, e cada idioma de destino tem sua própria coluna:

csv
id,en,notes,de
checkout.title,Complete your order,Shown on the last step,Bestellung abschließen
checkout.pay,"Pay now, or later",,
  • Colunas de idioma. Uma coluna pertence a um idioma quando seu cabeçalho corresponde ao código desse idioma, sem distinção entre maiúsculas e minúsculas: de e DE identificam a coluna de alemão, mas de-DE corresponde a outro idioma. O cabeçalho da coluna de origem é o sourceLocale definido na sua configuração.
  • Coluna de chave. Por padrão, a primeira célula do cabeçalho define o nome da coluna de chave. Para usar outra coluna, defina keyColumn na entrada do arquivo. A própria coluna de origem pode ser a coluna de chave, quando o texto de origem é usado como chave.
  • Outras colunas. As colunas que não são de chave nem de idioma, como notes, são preservadas byte a byte e nunca são enviadas para tradução.
  • Sintaxe. As células são separadas por vírgulas. Uma célula que contém vírgula, aspas ou quebra de linha deve ficar entre aspas duplas, e cada aspa dentro dela é duplicada (""). Arquivos separados por ponto e vírgula ou tabulação não são aceitos.

Configure a tradução de CSV #

Um arquivo CSV só é selecionado por uma entrada de arquivos cujo padrão termina em .csv, caso em que o formato é inferido, ou que define "format": "csv". Uma entrada com "format": "csv" seleciona apenas arquivos .csv. Um padrão amplo, como data/**/*, sem esse formato nunca seleciona um arquivo CSV. Isso evita que uma entrada existente passe a regravar arquivos de dados não relacionados. A extensão diferencia maiúsculas de minúsculas: um arquivo chamado strings.CSV não é traduzido, então renomeie-o para strings.csv.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "i18n/strings.csv", "keyColumn": "id" }]
}

O próprio arquivo é o destino de todos os idiomas, por isso targetPath é rejeitado nesse formato. As linhas do CSV não são comparadas com os controles de chave, então lockedKeys, preservedKeys e ignoredKeys também são rejeitados. A mesma configuração funciona na CLI e no GitHub App.

Quais linhas são traduzidas #

LinhaResultado
Chave e texto de origemTraduzida nos idiomas cujas células estão vazias ou desatualizadas.
Chave, célula de origem vaziaMantida como está; suas células de idioma não são alteradas.
Texto de origem, célula de chave vazia ou só com espaçosMantida como está, sem tradução. Atribua uma chave à linha para traduzi-la.
Chave e origem vazias, ou linha em brancoMantida como está, mesmo que contenha apenas espaços.

Uma célula de idioma que contém apenas espaços é considerada vazia. Uma célula preenchida é reutilizada enquanto o texto de origem da linha não tiver mudado desde o último push. Quando o texto de origem de uma linha muda, todas as células de idioma dessa linha são traduzidas novamente. Uma linha adicionada desde o último push mantém as células preenchidas, e apenas as vazias são traduzidas; se a chave de uma linha mudar, ela será considerada uma nova linha. As células preenchidas também são mantidas no primeiro push do arquivo, ao usar --force na CLI, em um comando do GitHub App que especifica arquivos sem --force e quando o arquivo enviado anteriormente não tem uma única coluna de origem ou de chave que permita a comparação, por exemplo, após a renomeação de uma delas. Um comando do GitHub App com --force traduz novamente todas as linhas do arquivo.

Os seguintes textos de origem são copiados em vez de traduzidos: textos compostos apenas por dígitos ASCII de 0 a 9, como 100; uma URL que começa com // ou tem um esquema composto por letras, dígitos ou sublinhados seguido de ://, e cujo endereço após // começa com localhost ou contém pelo menos um caractere, um ponto e pelo menos mais dois caracteres, como https://lingo.dev/docs; um ID de 22 caracteres composto apenas por letras e dígitos, com pelo menos uma letra maiúscula, uma letra minúscula e um dígito; e uma data ou uma data e hora no padrão ISO 8601, como 2024-01-15 ou 2024-01-15T10:00:00Z. O texto de origem é copiado para todas as células dos idiomas de destino na mesma linha, substituindo o conteúdo de cada uma. Essa linha não é enviada para tradução nem gera cobrança. Outros valores, como 1.5, 100%, um endereço de e-mail ou uma data em outro formato, como 15.01.2024, são traduzidos. Também são traduzidos os links mailto: e tel:, as URLs cujo esquema contém outros caracteres, como git+ssh://, e as URLs cujo endereço não começa com localhost e não contém um ponto nas condições descritas, como https://intranet ou https://a.b.

Quando um idioma de destino não tem coluna, ela é adicionada ao final do cabeçalho. Se houver várias colunas novas, elas serão adicionadas em ordem alfabética dos códigos de idioma. Em seguida, todas as linhas são completadas com células vazias para manter a tabela retangular. As linhas nunca são reordenadas, adicionadas ou removidas.

Erros #

O processamento do arquivo falha antes de qualquer tradução ou cobrança, com uma mensagem que identifica o problema, quando:

  • o keyColumn configurado não está no cabeçalho, ou a primeira célula do cabeçalho está vazia e nenhum keyColumn foi definido;
  • duas linhas têm a mesma chave, pois suas traduções seriam inseridas nas linhas erradas;
  • o cabeçalho não tem uma coluna para o idioma de origem;
  • a coluna de chave também é a coluna de um idioma de destino;
  • o cabeçalho contém mais de uma ocorrência do keyColumn configurado, do idioma de origem ou de um idioma de destino;
  • uma linha tem mais células que o cabeçalho;
  • uma célula delimitada por aspas não tem aspas de fechamento;
  • há texto após as aspas de fechamento na mesma célula.

Corrija o arquivo e execute o push novamente. A CLI exibe a mensagem uma única vez abaixo do arquivo, e não uma vez por idioma. Quando toda a execução falha, a linha final Run failed: repete a mensagem. O GitHub App a exibe na execução da verificação.

Corrija uma tradução existente #

Para fazer um ajuste pontual no texto, edite a célula. Para gerar uma tradução novamente, limpe a célula, mantenha o restante da linha e execute um push simples:

sh
lingo push --wait

Na CLI, --force reutiliza as células preenchidas, assim como faz com os Catálogos de strings da Apple. --key não restringe o escopo de um arquivo CSV: a CLI interrompe o push com um erro, e o GitHub App ignora o arquivo. O comando purge da CLI ignora o arquivo porque a origem e a saída compartilham o mesmo caminho. Revise todas as diferenças do arquivo antes de fazer o commit.