CSV
Traduza uma tabela CSV com uma coluna por idioma num único ficheiro e uma coluna à sua escolha como chave.
Uma tabela de tradução CSV guarda o texto de origem e todas as traduções num único ficheiro: uma linha por mensagem e uma coluna por idioma. O processador de ficheiros csv preenche as células dos idiomas de destino nesse ficheiro e grava o resultado no caminho de origem. Escreve apenas nas células dos idiomas de destino e acrescenta uma coluna quando um idioma ainda não tem uma, conforme descrito em Que linhas são traduzidas. As restantes colunas, a ordem das linhas, as aspas e os finais de linha mantêm-se inalterados. A marca de ordem de bytes UTF-8 no início do ficheiro não é preservada: o ficheiro é gravado sem essa marca. Por isso, se uma aplicação de folhas de cálculo depender dela para detetar UTF-8, poderá ser necessário importar o ficheiro como UTF-8.
Organizar a tabela #
A primeira linha que não esteja vazia nem contenha 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 a sua própria coluna:
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 corresponde a um idioma quando o cabeçalho coincide com o código desse idioma, sem distinguir maiúsculas de minúsculas:
deeDEidentificam a coluna de alemão, masde-DEcorresponde a um idioma diferente. O cabeçalho da coluna de origem é osourceLocaledefinido na sua configuração. - Coluna de chave. Por predefinição, a primeira célula do cabeçalho indica o nome da coluna de chave. Defina
keyColumnna entrada do ficheiro para utilizar outra coluna. A coluna de chave pode ser a própria coluna de origem, se o texto de origem servir de chave. - Outras colunas. As colunas que não correspondem à chave nem a um 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 contenha uma vírgula, uma aspa ou uma quebra de linha é delimitada por aspas duplas, e qualquer aspa no seu interior é duplicada (
""). Não são suportados ficheiros separados por ponto e vírgula ou tabulações.
Configurar a tradução de CSV #
Um ficheiro CSV só é selecionado por uma entrada de ficheiros cujo padrão termine em .csv, caso em que o formato é inferido, ou que defina "format": "csv". Uma entrada com "format": "csv" seleciona apenas ficheiros .csv. Um padrão abrangente como data/**/*, sem esse formato, nunca seleciona um ficheiro CSV. Assim, uma entrada existente não começa a reescrever ficheiros de dados não relacionados. A extensão distingue maiúsculas de minúsculas: um ficheiro com o nome strings.CSV não é traduzido, pelo que deve mudar-lhe o nome para strings.csv.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "i18n/strings.csv", "keyColumn": "id" }]
}O próprio ficheiro é o destino de todos os idiomas, pelo que targetPath é rejeitado neste formato. As linhas CSV não são comparadas com os controlos de chaves, pelo que lockedKeys, preservedKeys e ignoredKeys também são rejeitados. A mesma configuração funciona na CLI e na GitHub App.
Que linhas são traduzidas #
| Linha | Resultado |
|---|---|
| Chave e texto de origem | Traduzida nos idiomas cujas células estejam vazias ou desatualizadas. |
| Chave, célula de origem vazia | Mantida tal como está; as células dos idiomas não são alteradas. |
| Texto de origem, célula de chave vazia ou apenas com espaços | Mantida tal como está, sem tradução. Atribua-lhe uma chave para a traduzir. |
| Chave e origem vazias, ou linha em branco | Mantida tal como está, mesmo que contenha apenas espaços. |
Uma célula de idioma que contenha apenas espaços é considerada vazia. Uma célula preenchida é reutilizada se o texto de origem da respetiva linha não tiver mudado desde o último envio. 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 envio mantém as células preenchidas e só as células vazias são traduzidas; uma linha cuja chave tenha mudado é considerada uma nova linha. As células preenchidas também são mantidas no primeiro envio do ficheiro, com --force na CLI, num comando da GitHub App que indique ficheiros sem --force e quando o ficheiro enviado anteriormente não tem uma coluna única de origem ou de chave que permita a comparação, por exemplo, após a alteração do nome de uma delas. Um comando da GitHub App com --force volta a traduzir todas as linhas do ficheiro.
O texto de origem é copiado em vez de traduzido nos seguintes casos: quando contém apenas algarismos ASCII de 0 a 9, como 100; quando é um URL que começa por // ou tem um esquema composto por letras, algarismos ou sublinhados seguido de ://, e cujo endereço após // começa por localhost ou contém pelo menos um caráter, um ponto e pelo menos mais dois carateres, como https://lingo.dev/docs; quando é um ID de 22 carateres composto apenas por letras e algarismos, com pelo menos uma letra maiúscula, uma letra minúscula e um algarismo; e quando é uma data ou uma data e hora no formato ISO 8601, como 2024-01-15 ou 2024-01-15T10:00:00Z. O texto de origem é inserido em todas as células dos idiomas de destino da respetiva linha, substituindo o conteúdo de cada célula, e a linha não é enviada para tradução nem faturada. Outros valores, como 1.5, 100%, um endereço de e-mail ou uma data noutro formato, como 15.01.2024, são traduzidos. Também são traduzidas as ligações mailto: e tel:, os URL cujo esquema contém outros carateres, como git+ssh://, e os URL cujo endereço não começa por localhost nem contém um ponto nas condições descritas, como https://intranet ou https://a.b.
Quando um idioma de destino não tem coluna, é acrescentada uma no fim do cabeçalho. Se houver várias colunas novas, são acrescentadas por ordem alfabética dos códigos dos idiomas. Em seguida, todas as linhas são preenchidas com células vazias, conforme necessário, para que a tabela se mantenha retangular. As linhas nunca são reordenadas, adicionadas ou removidas.
Erros #
O processamento do ficheiro falha antes de qualquer tradução ou cobrança, com uma mensagem que identifica o problema, quando:
- o
keyColumnconfigurado não consta do cabeçalho, ou a primeira célula do cabeçalho está vazia e não está definido nenhumkeyColumn; - duas linhas têm a mesma chave, pois as respetivas traduções ficariam 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 indica mais de uma vez o
keyColumnconfigurado, o idioma de origem ou um idioma de destino; - uma linha tem mais células do que o cabeçalho;
- uma célula delimitada por aspas não tem aspas de fecho;
- existe texto a seguir às aspas de fecho na mesma célula.
Corrija o ficheiro e volte a enviá-lo. A CLI apresenta a mensagem uma única vez sob o ficheiro, e não uma vez por idioma. Quando toda a execução falha, a linha final Run failed: repete a mensagem. A GitHub App apresenta-a na execução de verificação.
Corrigir uma tradução existente #
Para alterar a redação de forma precisa, edite a célula. Para gerar novamente uma tradução, limpe essa célula, mantenha o resto da linha e execute um envio simples:
lingo push --waitNa CLI, --force reutiliza as células preenchidas, tal como acontece com os Apple String Catalogs. --key não restringe o âmbito de um ficheiro CSV: a CLI interrompe o envio com um erro e a GitHub App ignora o ficheiro. O comando purge da CLI ignora o ficheiro porque a origem e o resultado partilham o mesmo caminho. Reveja todas as diferenças do ficheiro antes de registar as alterações.