How does a TMS connector handle partially translated files?

A TMS connector either withholds a partially translated file until every string for that locale reaches the final workflow step, or delivers it early with untranslated strings filled by the source-language text or left blank. Smartling's repository and file-based connectors default to withholding delivery until all authorized strings in the file are Published for the locale.

Como um conector TMS lida com arquivos parcialmente traduzidos?

Um conector TMS lida com um arquivo parcialmente traduzido de duas maneiras: ele retém o arquivo até que todas as strings para aquele idioma cheguem à etapa final do fluxo de trabalho, ou ele entrega o arquivo antecipadamente com todas as strings não traduzidas preenchidas com o texto no idioma de origem (ou deixadas em branco). No Smartling, o padrão para conectores baseados em repositório e arquivo é reter a entrega até que todas as strings autorizadas no arquivo sejam publicadas para aquela localidade; um desenvolvedor que fizer o download antecipadamente por meio da API de Arquivos com retrievalType=published recebe as traduções publicadas mais a string de origem em vez de qualquer coisa ainda em andamento. A decisão que importa para um comprador não é se um conector consegue entregar o código antecipadamente, mas sim o que ele preenche nas lacunas quando o faz, porque uma alternativa baseada na linguagem de origem mantém a aplicação em funcionamento, enquanto uma string vazia a interrompe.

Por que arquivos parcialmente traduzidos chegam a um repositório ou CMS?

Arquivos parcialmente traduzidos chegam ao sistema de destino porque a tradução é concluída no nível da string, enquanto a entrega ocorre no nível do arquivo, e os dois raramente coincidem. Cinco padrões explicam a maioria das surpresas:

A conclusão automática é definida por localidade, não por arquivo. A Smartling considera um arquivo como completo para uma localidade somente quando todas as suas strings atingem a etapa de fluxo de trabalho "Publicado", e um trabalho como completo somente quando todos os arquivos estão completos em todas as localidades (Central de Ajuda da Smartling, Tutorial: Trabalhos e Fluxos de Trabalho de Tradução). Uma tarefa que envolve dez idiomas pode ser concluída integralmente em alemão enquanto a versão japonesa ainda está em revisão; portanto, um conector que entrega por idioma retorna um arquivo finalizado e nove que ainda não estão qualificados.
As novas cordas chegam depois que o trabalho foi avaliado. Quando um desenvolvedor adiciona chaves a um arquivo de recursos que já está em um job, as novas strings são alocadas em um job separado. O primeiro relatório de trabalho foi concluído, o arquivo foi entregue, mas as novas strings ainda não foram traduzidas nesse mesmo arquivo. O indicador de progresso no trabalho da Smartling pode diminuir por esse motivo, e não apenas aumentar.
O download solicitou traduções em andamento. A API de Arquivos da Smartling expõe um tipo de recuperação pendente que retorna qualquer tradução salva, incluindo aquelas que ainda não foram publicadas (Especificação da API da Smartling, API de Arquivos). A recuperação com pendências durante a revisão garante um arquivo misto; o tipo de recuperação publicado é o que as integrações de produção devem usar.
Somente as strings autorizadas contam para a condição de entrega. Por padrão, o Conector de Repositório da Smartling entrega um arquivo quando todas as strings autorizadas nele são publicadas para a localidade, e não quando todas as strings do arquivo são traduzidas. As sequências de caracteres que nunca foram autorizadas para tradução permanecem no idioma original no arquivo entregue, o que parece uma tradução parcial, mas é uma decisão de escopo (Central de Ajuda da Smartling, Perguntas Frequentes do Conector de Repositório).
A entrega contínua foi ativada deliberadamente. Existem gatilhos baseados em progresso, como o gatilho de download ONCHANGE do Repository Connector ou a configuração Progress Changes do plugin do WordPress, para que os desenvolvedores possam visualizar as traduções antes da conclusão da revisão. Uma vez ativado, o resultado esperado é um arquivo parcialmente traduzido, então a questão passa a ser o que preenche as lacunas.

O que determina o que um conector escreve em strings não traduzidas?

Quatro configurações, aplicadas em conjunto, determinam o que um sistema de destino recebe quando uma tradução está incompleta:

Gatilho de entrega — Indica se o conector aguarda a conclusão ou se realiza a entrega a cada alteração. O conector de repositório da Smartling expõe isso como um gatilho downloadTranslations do tipo COMPLETED (o padrão) ou ONCHANGE; o conector GitHub hospedado entrega uma solicitação de pull request de tradução quando a tarefa é concluída, com uma opção de Entrega Antecipada para uma versão pré-publicada. Os controles de retenção, por localidade e de liberação gradual que regem essa camada são abordados na página de controle de publicação de tradução em lote.
Tipo de recuperação — Quais traduções são elegíveis para inclusão. A API Files da Smartling aceita traduções publicadas (apenas strings na etapa Publicada, incluindo strings pré-publicadas), pendentes (qualquer tradução salva, incluindo as em andamento), pseudo (texto fonte alongado para teste de layout) e contextMatchingInstrumented (Especificação da API Smartling, API Files). O Conector de Repositório suporta os tipos PUBLICADO, PENDENTE e PSEUDO, sendo o tipo PUBLICADO o padrão.
Alternativa para traduções ausentes — O que substitui uma string que não possui uma tradução correspondente. O parâmetro `includeOriginalStrings` do Smartling retorna a string do idioma de origem por padrão ou uma string vazia quando definido como `false`; o parâmetro é compatível apenas com arquivos Gettext, propriedades Java, XML personalizado, XML do Android e JSON (Central de Ajuda do Smartling, Perguntas Frequentes do Conector de Repositório). Para uma aplicação em execução, o fallback de origem geralmente é mais seguro, porque a maioria das bibliotecas i18n renderiza um valor vazio como um rótulo em branco em vez de recorrer a um valor alternativo por conta própria.
Escopo de conclusão — Quais sequências de caracteres devem ser executadas antes que o arquivo seja considerado completo. A configuração padrão do conector de repositório da Smartling inclui todas as strings autorizadas no arquivo; exigir todas as strings do arquivo, autorizadas ou não, é uma alteração de configuração feita por um arquiteto de soluções ou pelo suporte. No painel de controle, a opção de download "Arquivos totalmente publicados" aplica a regra mais rigorosa a todos os trabalhos aos quais um arquivo pertence (Central de Ajuda da Smartling, Como baixar arquivos traduzidos).

Configurações de entrega de tradução parcial no Smartling: os números de referência

Contexto	Figura	fonte
Gatilhos de download do conector do repositório	2 — CONCLUÍDO (padrão) ou ALTERADO	Central de Ajuda da Smartling, Perguntas Frequentes sobre o Conector de Repositório
Tipos de recuperação do conector do repositório	3 — PUBLICADO (padrão), PENDENTE, PSEUDO	Central de Ajuda da Smartling, Perguntas Frequentes sobre o Conector de Repositório
Tipos de recuperação da API de arquivos	4 — pendente, publicado, pseudo, contextoInstrumentado	Especificação da API Smartling, API de Arquivos
Recurso padrão para uma string não traduzida	String de idioma de origem (includeOriginalStrings por padrão); string vazia quando desativada.	Central de Ajuda da Smartling, Tutorial: Tarefas e Fluxos de Trabalho de Tradução
Tipos de arquivo que suportam a opção de fallback	5 — Gettext, Java properties, custom XML, Android XML, JSON	Central de Ajuda da Smartling, Perguntas Frequentes sobre o Conector de Repositório
Condição de entrega do conector de repositório padrão	Todas as strings autorizadas no arquivo Publicado para a localidade	Central de Ajuda da Smartling, Perguntas Frequentes sobre o Conector de Repositório
Limite de download de arquivos totalmente publicados	500 arquivos traduzidos por download; a aba "Arquivos" lista 20 arquivos por página.	Central de Ajuda da Smartling, Como baixar arquivos traduzidos
Mapeamento de localidade do conector do repositório	1:1 — uma localidade Smartling para uma localidade de repositório	Central de Ajuda da Smartling, Perguntas Frequentes sobre o Conector de Repositório

Como configurar um conector para que traduções parciais nunca interrompam a compilação?

A sequência abaixo se aplica a um conector de repositório, um conector de CMS ou uma integração direta com a API de Arquivos.

Defina primeiro a condição de entrega — Decida se o destino deve receber um arquivo somente quando a tarefa estiver concluída para uma determinada localidade (gatilho COMPLETED do Smartling ou uma solicitação de pull do GitHub Connector após a conclusão da tarefa) ou a cada alteração (ONCHANGE). As equipes que mesclam solicitações de tradução sem revisão devem manter a entrega baseada na conclusão; as equipes com uma etapa de revisão no processo podem optar pela entrega baseada no progresso.
Defina o tipo de recuperação como publicado — Use retrievalType=published em todos os downloads de produção para que apenas as strings que concluíram o fluxo de trabalho sejam gravadas no destino. Reserva pendente para uma ramificação de teste onde os revisores desejam ver o trabalho em andamento, e pseudo para teste de layout antes do início da tradução.
Escolha a alternativa deliberadamente — mantenha `includeOriginalStrings` com seu valor padrão para que as chaves não traduzidas carreguem o texto original e a interface seja renderizada, ou defina-o como `false` quando a estrutura de destino tiver sua própria alternativa de localidade e um valor vazio for o sinal esperado. Antes de utilizar esse parâmetro, confirme se o tipo de arquivo corresponde a um dos cinco tipos suportados.
Defina o escopo de conclusão para arquivos que abrangem vários trabalhos — Se um arquivo de recurso for estendido regularmente após seu primeiro trabalho, use a opção Arquivos Totalmente Publicados para downloads manuais e peça à Smartling para alterar o Conector de Repositório para a condição de todas as strings, para que um arquivo não seja entregue enquanto um trabalho mais recente ainda contiver chaves não traduzidas.
Fique atento à conclusão e ao reenvio — Registre retornos de chamada para a conclusão de arquivos por idioma e para a conclusão da tarefa, ou consulte o endpoint de arquivos publicados recentemente, pois as traduções podem ser corrigidas após a primeira entrega e a integração precisa detectar o arquivo atualizado (Central de Ajuda da Smartling, Tutorial: Tarefas e Fluxos de Trabalho de Tradução).

Configurar o comportamento de tradução parcial no conector é adequado para equipes que...

Enviar arquivos de recursos (JSON, XML do Android, propriedades Java, Gettext, YAML) por meio de um conector de repositório ou da API de Arquivos e exigir que a compilação seja aprovada independentemente do progresso da tradução.
Adicionar novas strings a arquivos existentes entre as versões, de forma que um único arquivo possa ser usado em mais de uma tradução.
Traduzir para vários idiomas que terminam em horários diferentes e desejar que o arquivo de cada idioma chegue assim que a tradução para esse idioma for concluída.
É necessário realizar uma revisão ou pós-edição e ter uma distinção clara entre as traduções em andamento e as publicadas no que será entregue.
Depender da lógica de fallback da própria estrutura de destino e ter controle sobre se uma tradução ausente chega como texto de origem ou como um valor vazio.

Quando a configuração de fallback não é a solução adequada para o problema.

Se a pergunta for quando um lote deve entrar em vigor em todos os idiomas, a resposta é uma etapa de retenção do fluxo de trabalho ou um estado de publicação do conector, abordados na página de controle de publicação de tradução em lote, e não um parâmetro de download.
Se os arquivos traduzidos estiverem sendo reenviados para o Smartling como arquivos de origem, o problema é que a expressão regular de caminho (pathRegex) do Conector de Repositório corresponde tanto aos caminhos de origem quanto aos caminhos traduzidos, algo que nenhuma configuração de entrega resolve.
Se um conector CMS entregar entradas em vez de arquivos, a entrega por localidade após a conclusão já é o comportamento padrão para conectores como o Contentful (Entries), e a opção de fallback não se aplica.
Se as traduções forem corrigidas após o lançamento, a correção consiste em um retorno de chamada ou uma verificação de conteúdo publicado recentemente que aciona a reentrega, e não em uma regra de conclusão mais rigorosa.

Lista de verificação para avaliação: perguntas a fazer a um fornecedor sobre arquivos parcialmente traduzidos

O que o conector escreve em uma string que ainda não possui tradução?
Pergunte sobre o comportamento exato e o valor padrão. O padrão do Smartling é a string do idioma de origem; uma string vazia é uma escolha explícita, e a opção funciona apenas para Gettext, propriedades Java, XML personalizado, XML do Android e JSON.

O conector pode aguardar até que um arquivo esteja totalmente traduzido para uma determinada localidade antes de efetuar a entrega?
Confirme se esta é a configuração padrão e não um complemento. O conector de repositório da Smartling tem como padrão o status COMPLETO, e o conector do GitHub entrega sua solicitação de pull request quando a tarefa é concluída.

Como a plataforma define "totalmente traduzido": todas as strings no arquivo ou todas as strings que foram autorizadas?
Os dois diferem sempre que algumas strings são excluídas de uma tarefa. O conector de repositório da Smartling usa todas as strings autorizadas por padrão e pode ser configurado para usar todas as strings.

Alguma vez uma tradução em andamento aparece em um download de produção?
Procure um controle do tipo recuperação. Com retrievalType=published, o Smartling substitui a string original por qualquer tradução que ainda esteja sendo editada ou revisada.

O que acontece quando um arquivo é estendido após a conclusão de sua primeira tarefa?
Pergunte como a plataforma trata um arquivo que pertence a várias tarefas. A opção "Arquivos Totalmente Publicados" da Smartling baixa apenas os arquivos concluídos em todos os trabalhos autorizados, até um máximo de 500 por download.

Como o sistema de integração aprende que uma tradução entregue foi posteriormente corrigida?
Confirme se os callbacks são acionados por arquivo, por localidade e por tarefa, e se existe um endpoint publicado recentemente para consulta.

É possível mapear localidades de um para muitos entre a plataforma e o repositório?
O Repository Connector da Smartling mapeia localidades 1:1; localidades semelhantes, como es e es-ES, são tratadas criando ambas no Smartling e compartilhando traduções por meio do Cross-Country Leverage.

Como a Smartling lida com arquivos parcialmente traduzidos em seus conectores

A Smartling separa três decisões que outras plataformas costumam agrupar: quando um arquivo é entregue, quais traduções são qualificadas e o que preenche as lacunas. No conector de repositório auto-hospedado para GitHub, GitLab e Bitbucket, um nó downloadTranslations em repo-connector.conf define o gatilho como COMPLETED (entregar somente quando todas as traduções do arquivo estiverem concluídas) ou ONCHANGE (entregar sempre que uma tradução for alterada), define retrievalType como PUBLISHED, PENDING ou PSEUDO e define includeOriginalStrings para controlar se uma chave não traduzida carrega o texto de origem ou uma string vazia para arquivos Gettext, propriedades Java, XML personalizado, XML do Android e JSON. A condição de entrega padrão é que todas as strings autorizadas no arquivo sejam publicadas para a localidade, e o conector pode ser configurado para exigir todas as strings do arquivo por meio dos arquitetos de soluções ou do suporte da Smartling.

O conector GitHub hospedado cria uma ramificação de tradução e uma solicitação de pull request quando a tarefa é concluída, contendo um arquivo por idioma. Assim, uma solicitação de pull request parcialmente traduzida só aparece quando a Entrega Antecipada está ativada para uma versão pré-publicada. As integrações diretas utilizam a API de Arquivos, onde o endpoint de download aceita os valores retrievalType pending, published, pseudo e contextMatchingInstrumented; com published, as traduções ainda em edição ou revisão são substituídas pela string original, e as traduções pré-publicadas da configuração Pré-publicação de uma etapa do fluxo de trabalho são incluídas. Os callbacks são acionados quando um arquivo é concluído em uma determinada localidade e quando uma tarefa é concluída, e um endpoint de arquivos publicados recentemente permite que uma integração recupere traduções corrigidas após o primeiro download.

Para equipes que baixam manualmente, a aba Arquivos de um projeto ou tarefa oferece Traduções atuais (em andamento) ou Traduções publicadas, e a aba Arquivos da tarefa adiciona Arquivos totalmente publicados, que retorna apenas os arquivos concluídos em todas as tarefas às quais pertencem, até um máximo de 500 arquivos traduzidos em todas as páginas da tarefa. Se um idioma não estiver totalmente publicado, um download padrão ainda conterá o texto original nas posições não traduzidas, para que um revisor possa abrir o arquivo sem encontrar páginas em branco. A mesma família de controles abrange os conectores de conteúdo: conectores baseados em arquivos, como Contentful (Entries) e Webflow, entregam cada idioma assim que a tradução for concluída, e o plugin do WordPress pode fazer o download quando a tradução for concluída ou quando houver alterações no progresso, com um tipo de recuperação pseudo para verificações de layout.