Guia de tradução Sweet Home 3D

Introdução

Você fala um idioma estrangeiro ainda não suportado no Sweet Home 3D e gostaria de contribuir para a sua tradução para esse idioma? A partir da versão 2.3, o Sweet Home 3D suporta arquivos SH3L e este guia ensinará você a criar esse arquivo sozinho. Um arquivo SH3L é um arquivo de idioma auto instalável e os usuários só precisam clicar duas vezes em um arquivo SH3L para traduzir o Sweet Home 3D para o idioma descrito por esse arquivo.

Instruções básicas

Criar um arquivo SH3L consiste em:

baixar uma versão em inglês dos arquivos para traduzir,
descompactar o arquivo baixado,
adicionar um sufixo de 2 letras correspondente ao seu idioma aos arquivos .properties que ele contém,
traduzir o texto nos arquivos .properties,
convertê-los para a codificação ASCII,
traduzir o texto de ajuda nos arquivos .html (não obrigatório, mas será muito útil para os usuários),
compactar os arquivos .properties e os arquivos de ajuda de volta em um arquivo com uma extensão SH3L,
clicar duas vezes no arquivo SH3L para testar sua tradução no Sweet Home 3D,
distribuir seu arquivo SH3L.

Instruções detalhadas

Se você não tem receio das instruções básicas anteriores, siga em frente com as próximas etapas.

Obtendo a versão em inglês

Baixe o arquivo em /SweetHome3DTranslation.zip (versão 7.5) e descompacte-o com as ferramentas do seu sistema.
SweetHome3DTranslation.zip contém um conjunto de arquivos com extensões .properties e .html colocados em subpastas, conforme mostrado na figura 1.

Todos os arquivos .properties e .html contêm a versão em inglês dos textos que você terá que traduzir para o seu idioma:

os arquivos package.properties descrevem rótulos, menus e itens de menu mostrados na interface do usuário do Sweet Home 3D,
os arquivos basic.properties e metal.properties descrevem os rótulos de diálogo padrão,
aqueles que terminam com Catalog.properties descrevem os nomes dos móveis e as texturas disponíveis no software,
os arquivos .html contêm o texto da ajuda do Sweet Home 3D.

Renomeando arquivos dependendo do seu idioma

Antes de traduzir os arquivos .properties, você deve renomear cada um deles adicionando ao seu nome um sublinhado seguido pelo código ISO de 2 caracteres correspondente ao seu idioma. Você encontrará este código na última coluna do documento https://www.loc.gov/standards/iso639-2/php/English_list.php.
Então, se você quiser traduzir os arquivos de ajuda, você também deve renomear o subdiretório en de help com esse código de 2 letras também.
Por exemplo, o código ISO para tcheco é cs. Se você quiser traduzir o Sweet Home 3D para tcheco, cada nome de arquivo deve ser sufixado por _cs, e você deve renomear os arquivos como mostrado na figura 2.

Figura 2. Arquivos de propriedades com seu sufixo de código ISO

Traduzindo arquivos de propriedades

Os arquivos .properties são arquivos de texto simples e você pode editá-los com qualquer editor de texto como Wordpad, TextEdit ou emacs. Por exemplo, o arquivo com/eteks/sweethome3d/package.properties no Sweet Home 3D 3.0 contém o seguinte texto:

# package.properties 10 oct. 2007
# 
# Copyright (c) 2024 Space Mushrooms <[email protected]>. All Rights Reserved.
# 
# This program is free software; you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free Software
# Foundation; either version 2 of the License, or (at your option) any later
# version.
# 
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
# FOR A PARTICULAR PURPOSE.  Veja a Licença Pública Geral GNU para mais
# detalhes.
# 
# Você deveria ter recebido uma cópia da Licença Pública Geral GNU junto com
# este programa; se não, escreva para a Free Software Foundation, Inc., 59 Temple
# Place, Suite 330, Boston, MA 02111-1307 USA

# Recursos para a classe HomeFramePane
HomeFramePane.untitled=Sem título


# Recursos para a classe MacOSXConfiguration
MacOSXConfiguration.WINDOW_MENU.Name=Janela
MacOSXConfiguration.MINIMIZE.Name=Minimizar
MacOSXConfiguration.ZOOM.Name=Zoom
MacOSXConfiguration.BRING_ALL_TO_FRONT.Name=Trazer tudo para a frente


# Recursos para a classe SweetHome3D
SweetHome3D.3DError.message=<html> O Sweet Home 3D será encerrado agora devido a um erro fatal
    <br>no sistema de renderização 3D. Por favor, atualize os drivers DirectX/OpenGL
    <br>da sua placa de vídeo. 
SweetHome3D.3DError.title=Erro 3D
    
SweetHome3D.confirmSaveAfter3DError.message=<html> O Sweet Home 3D deve ser encerrado agora devido a um erro fatal em
    <br>sistema de renderização 3D. Você quer salvar todas as casas modificadas? 
SweetHome3D.confirmSaveAfter3DError.title=Erro 3D
SweetHome3D.confirmSaveAfter3DError.save=Salvar
SweetHome3D.confirmSaveAfter3DError.doNotSave=Não salvar

Um arquivo .properties contém três tipos de linhas:

as linhas que começam com um caractere # são comentários (mostrados em verde no exemplo anterior). Alguns comentários contêm informações legais, alguns dão informações para desenvolvedores ou para tradutores. Mantenha estas linhas inalteradas.
linhas vazias são usadas apenas para separar as várias partes de um arquivo .properties.
as outras linhas começam com algum texto usado pelo Sweet Home 3D como uma chave para encontrar um texto exibido na tela (mostrado em azul no exemplo anterior). Seguindo esta chave, cada uma destas linhas contém um sinal de igual (=) e um texto em um determinado idioma. Seu trabalho começa a partir dos sinais de igual. Não altere o texto da chave e substitua o texto em inglês após o sinal de igual pela sua tradução.

Casos especiais:

Os textos que começam com uma <html> tag contêm algum texto em formato HTML. Estes textos contêm algumas outras tags HTML entre < e > sinais, como <br> no exemplo anterior, que representa um retorno de carro no meio de textos longos. Não remova estas tags HTML, elas ajudam o Sweet Home 3D a apresentar corretamente alguns textos. Traduzir texto entre tags HTML não é muito difícil, exceto talvez para o pior texto HTML que é o valor da chave WallPanel.wallOrientationLabel.text .
Para evitar linhas longas no editor de texto, algumas linhas são divididas em duas ou mais linhas e, em seguida, separadas por barras invertidas \, como a linha que começa por SweetHome3D.3DError.message no exemplo anterior. Nesse caso, não remova o \ sinal localizado no final de uma linha porque indica que a próxima linha segue a linha atual.
Alguns textos contêm uma sequência de caracteres especiais começando com um sinal % , como %s, %d, %1$s, %2$s… Estas sequências de caracteres serão substituídas por um nome de arquivo, uma unidade ou um número quando necessário, então não as remova.
Por exemplo, a sequência de caracteres %s no texto da seguinte chave HomeFurniturePanel.widthLabel.text:
```
HomeFurniturePanel.widthLabel.text=Largura (%s):
```
será substituído pela unidade atualmente em uso. As duas sequências de caracteres %1$d e %2$d que aparecem no texto da seguinte chave PrintPreviewPanel.pageLabel.text:
```
PrintPreviewPanel.pageLabel.text=Página  %1$d/%2$d
```
aparecerá na tela como um número de página e a contagem de páginas, e você deve traduzir apenas a palavra Page.
Alguns textos também contêm a sequência de caracteres especiais \n, como no exemplo a seguir:
```
HomeController.saveError=Não é possível salvar a casa em
"%s"
```
Esta sequência de caracteres é exibida pelo Sweet Home 3D como um retorno de carro para dividir uma linha na tela, e você não deve removê-los.
O valor da chave HelpController.helpIndex indica o diretório onde os arquivos de ajuda podem ser encontrados. Se você traduzir os arquivos de ajuda .html, você deve substituir o subdiretório en encontrado pelo código de 2 letras do seu idioma.
Por exemplo, se você traduzir a ajuda para tcheco, deve se tornar:
```
HelpController.helpIndex=/com/eteks/sweethome3d/viewcontroller/resources/help/cs/index.html
```

O texto das chaves que terminam com .mnemonic são usados pelo Sweet Home 3D para adivinhar qual letra em um rótulo ou um item de menu deve ser sublinhada para acesso pelo teclado. Esta letra mnemônica depende da palavra exibida e você deve encontrar uma única por caixa de diálogo ou menu.
Por exemplo, os seguintes textos e mnemônicos exibidos na caixa de diálogo de modificação de móveis:

HomeFurniturePanel.nameLabel.text=Nome:
HomeFurniturePanel.nameLabel.mnemonic=N
HomeFurniturePanel.nameVisibleCheckBox.text=Exibir nome no plano
HomeFurniturePanel.nameVisibleCheckBox.mnemonic=S
HomeFurniturePanel.widthLabel.text=Largura (%s):
HomeFurniturePanel.widthLabel.mnemonic=W

pode ser traduzido em francês por:

HomeFurniturePanel.nameLabel.text=Nom :
HomeFurniturePanel.nameLabel.mnemonic=N
HomeFurniturePanel.nameVisibleCheckBox.text=Afficher le nom dans le plan
HomeFurniturePanel.nameVisibleCheckBox.mnemonic=S
HomeFurniturePanel.widthLabel.text=Largeur (%s) :
HomeFurniturePanel.widthLabel.mnemonic=L

Use o Sweet Home 3D ou a página de importação de modelos 3D para ajudá-lo a traduzir os arquivos .properties que terminam com Catalog.properties.

Convertendo arquivos de propriedades para codificação ASCII

Se você traduziu textos para um idioma com letras que não pertencem à codificação ISO-8859-1 (principalmente idiomas da Europa Central e Oriental e idiomas com um alfabeto não latino), você terá que converter todos os seus arquivos .properties para uma codificação ASCII suportada pelo Sweet Home 3D. Esta conversão pode ser feita com a ferramenta native2ascii fornecida com o JDK ou pode ser realizada com o seguinte formulário.
Para cada arquivo .properties, crie um backup desse arquivo, copie/cole o texto para converter na seguinte área de texto, clique no botão Converter e copie/cole o texto convertido de volta em seu arquivo .properties.

A ferramenta de conversão substituirá cada caractere não ASCII (letras latinas acentuadas e letras não latinas) por uma sequência começando por \u e seguida por um código de 4 dígitos hexadecimais correspondente a esse caractere em Unicode. Miseravelmente, esta conversão tornará seu texto bastante ilegível para um humano, mas se você não realizá-la, o Sweet Home 3D não poderá exibir os caracteres da sua tradução corretamente. Esta é a razão pela qual você deve criar um backup de seus arquivos .properties originais, caso queira alterá-los mais tarde.
Se você quiser editar diretamente arquivos .properties convertidos para ASCII, você também pode usar o aplicativo Properties Editor disponível como um arquivo executável Jar aqui.

Traduzindo os arquivos de ajuda

Uma boa tradução do Sweet Home 3D também deve incluir a tradução de seus arquivos de ajuda. Traduzir todos os arquivos .html é uma tarefa longa, mas realmente ajudará os usuários a aprender o software e evitar alguns pedidos de suporte no fórum do Sweet Home 3D. Use qualquer editor HTML para traduzir estes arquivos, tentando manter os links que ele contém e sua folha de estilo inalterados.
Uma vez traduzido, você também deve criar capturas de tela das caixas de diálogo em seu idioma para substituir as imagens encontradas em com/eteks/sweethome3d/viewcontroller/resources/help/en/images. Para poder criar tais capturas de tela, crie e teste um primeiro arquivo SH3L com os seguintes passos (uma vez que um arquivo SH3L contendo arquivos .properties traduzidos exista, você também pode solicitar ao desenvolvedor do Sweet Home 3D para gerar as capturas de tela).

Criando o arquivo SH3L

Uma vez que todos os arquivos .properties e .html são traduzidos e convertidos para ASCII, se necessário (ou mesmo antes, se você quiser testar este procedimento), você deve compactá-los em um arquivo. Dependendo do seu sistema, criar um arquivo zip pode ser feito com o seguinte procedimento:

no Windows, selecione a pasta com contendo todos os arquivos traduzidos e escolha Enviar para > Pasta compactada no seu menu de contexto,
no Mac OS X, selecione a pasta com contendo todos os arquivos traduzidos e escolha o item de menu Arquivo > Comprimir « com »,
no Linux, selecione a pasta com contendo todos os arquivos traduzidos, escolha Criar arquivo… no seu menu de contexto e, em seguida, selecione .zip na lista de formatos.

Finalmente, altere a extensão .zip do arquivo zip para .sh3l. Um arquivo SH3L pode ter qualquer nome, mas para evitar conflitos com arquivos SH3L existentes, você deve nomeá-lo a partir do idioma que ele contém e da versão do Sweet Home 3D que você traduziu (por exemplo, French-4.1.sh3l poderia ser um bom nome para a tradução francesa do Sweet Home 3D 4.1).

Testando um arquivo SH3L

Para testar a tradução, clique duas vezes em um arquivo SH3L ou escolha-o com o botão Import language library file exibido na parte superior do painel Preferências. Isso iniciará o Sweet Home 3D e traduzirá sua interface de usuário para o idioma descrito no arquivo SH3L. Isso também copiará o arquivo SH3L em uma pasta dependendo do seu sistema:

no Windows Vista / 7 / 8 / 10 / 11, esta pasta é C:\Users\usuário\AppData\Roaming\eTeks\Sweet Home 3D\languages,
no Windows XP e versões anteriores do Windows, esta pasta é C:\Documents and Settings\usuário\Application Data\eTeks\Sweet Home 3D\languages,
no macOS, é a subpasta Library/Application Support/eTeks/Sweet Home 3D/languages da sua pasta de usuário,
no Linux e outros Unix, é a subpasta .eteks/sweethome3d/languages da sua pasta de usuário,
com a versão portátil do Sweet Home 3D, é a subpasta data/languages da pasta onde o aplicativo Sweet Home 3D está armazenado,

Observe também que, durante o desenvolvimento do seu arquivo SH3L, você provavelmente terá que reiniciar o Sweet Home 3D para ver as alterações no seu arquivo SH3L.

Distribuindo arquivos SH3L

Quando seu arquivo SH3L estiver pronto, você pode propô-lo a qualquer pessoa, anunciá-lo aos usuários do Sweet Home 3D na parte do fórum reservada a idiomas estrangeiros ou em outros lugares. Se você concordar, ele poderá ser disponibilizado neste site na página sobre traduções suportadas pelo Sweet Home 3D.

Atualizando arquivos SH3L

Algumas versões do Sweet Home 3D trazem novos recursos para traduzir, outras não. Se você não traduzir os rótulos da interface do usuário que correspondem a esses novos recursos, o Sweet Home 3D funcionará, mas todos os novos rótulos aparecerão em inglês. Para encontrar as novas chaves e as chaves atualizadas nos arquivos .properties, você pode usar um recurso oferecido pelo SourceForge.net que permite comparar duas versões de um arquivo de projeto:

Pesquise as datas das versões do Sweet Home 3D que você deseja comparar no histórico (por exemplo, 19 de julho de 2015 para a versão 5.0 e 2 de fevereiro de 2015 para a versão 4.6)
Clique no arquivo .properties ou .html que você deseja atualizar na figura 1,
Selecione as duas caixas de seleção do número de revisão que corresponde à data da versão do arquivo atualizado, escolhendo a data que está logo antes de uma data de versão do Sweet Home 3D,
Clique no botão Compare.

O último clique mostrará as diferenças entre as duas versões desse arquivo .properties (por exemplo, este link mostrará as diferenças entre a versão 4.6 e a versão 5.0 do arquivo com/eteks/sweethome3d/viewcontroller/package.properties).

Depois de encontrar as diferenças, atualize sua tradução, adicionando novos nomes de chave, se necessário, e lance uma nova versão de sua tradução.