Localizzazione dell'editor e della documentazione

Godot aims to make game development available to everyone, including people who may not know or be comfortable with English. Therefore, we do our best to make the most important resources available in many languages, thanks to the translation effort of the community.

Tali risorse includono:

1. L'interfaccia dell'editor Godot.

2. Il riferimento classi, disponibile sia online sia nell'editor.

3. La documentazione online (manuale dell'editor e tutorial).

To manage translations, we use the GNU gettext file format (PO files), and the open source Weblate web-based localization platform, which allows easy collaboration of many contributors to complete the translation for the various components, and keep them up to date. Click the bold links above to access each resource on Weblate.

Questa pagina offre una panoramica del processo generale di traduzione su Weblate, nonché alcune istruzioni specifiche per ogni risorsa, ad esempio su come gestire determinate parole chiave o la localizzazione di immagini.

Suggerimento

Tradurre tutti i contenuti ufficiali di Godot è un'impresa colossale, quindi consigliamo di dare priorità alle risorse come sono elencate sopra: prima l'interfaccia dell'editor, poi il riferimento alla classe, e poi la documentazione online.

Uso di Weblate per le traduzioni

Sebbene le nostre traduzioni risiedano nei repository Git del motore Godot e della sua documentazione, tutti gli aggiornamenti delle traduzioni sono gestiti tramite Weblate, pertanto non sono accettate richieste di pull dirette ai repository Git. Le traduzioni vengono sincronizzate manualmente tra Weblate e i repository Godot dai manutentori.

Dovresti quindi registrarti su Weblate per contribuire alle traduzioni di Godot.

Una volta effettuato l'accesso, vai alla risorsa di Godot a cui vuoi contribuire (in questa pagina useremo la traduzione dell'editor come esempio) per trovare l'elenco di tutte le lingue:

Vedi anche

Non esitate a consultare la documentazione di Weblate sul flusso di lavoro di traduzione per maggiori dettagli.

Aggiungere una nuova lingua

Se la tua lingua è già presente nell'elenco, clicca sul suo nome per andare alla panoramica e salta il resto di questa sezione.

Se la tua lingua non è presente nell'elenco, scorri fino in fondo all'elenco delle lingue e clicca sul pulsante "Comincia una nuova traduzione", quindi seleziona la lingua in cui desideri tradurre:

Importante

Se la tua lingua è parlata in diversi paesi aventi solamente limitate varianti regionali, si consiglia di aggiungerla con la sua variante generica (ad esempio fr per il francese) anziché con una variante regionale (ad esempio fr_FR per il francese (Francia), fr_CA per il francese (Canada) o fr_DZ per il francese (Algeria)).

Godot ha un'enorme quantità di contenuti da tradurre, quindi duplicare il lavoro per le varianti regionali si dovrebbe fare solo se le variazioni linguistiche sono sufficientemente importanti. Inoltre, se una traduzione viene realizzata per una variante regionale, sarà disponibile automaticamente solo per gli utenti che si trovano in quella regione (o che hanno la lingua del sistema configurata per quella regione).

Quando le varianti regionali sono sufficientemente importanti da giustificare traduzioni separate, consigliamo di concentrarsi, se possibile, a completare prima una variante generica, poi a duplicare la traduzione completa per le varianti regionali e apportare le modifiche necessarie. Questa è in genere una buona strategia, ad esempio, per lo spagnolo (lavora prima su es, quindi duplicalo in es_AR, es_ES, es_MX, ecc. se necessario) o il portoghese (pt_BR contro pt_PT).

Interfaccia di traduzione

Una volta selezionata una lingua, vedrai una panoramica dello stato della traduzione, incluso il numero di stringhe rimanenti da tradurre o revisionare. Ogni elemento si può cliccare e usare per sfogliare l'elenco corrispondente. È anche possibile cliccare sul pulsante "Traduci" per cominciare con l'elenco delle stringhe su cui è necessario intervenire.

Dopo aver selezionato un elenco cliccando su "Traduci", vedrai l'interfaccia di traduzione principale, dove viene svolto tutto il lavoro:

In quella pagina, hai:

• Una barra degli strumenti che permette di scorrere le stringhe dell'elenco attuale, di passare a un altro elenco predefinito o di fare una ricerca personalizzata, ecc. Esiste anche una modalità di editing "Zen" con un'interfaccia semplificata.

• La stringa effettiva su cui stai lavorando nel pannello "Traduzione". Di predefinito, dovrebbe essere presente la stringa di origine in inglese e una casella di modifica per la tua lingua. Se hai familiarità con altre lingue, puoi aggiungerle nelle tue impostazioni utente per ricavare più contesto per la traduzione. Una volta completata la modifica della stringa attuale, premi "Salva" per confermare le modifiche e passare alla voce successiva. In alternativa, usa il pulsante "Salta" per ignorarla. La casella di spunta "Necessita di modifica" indica che la stringa originale è stata aggiornata, e che la traduzione deve quindi essere rivista per tenere conto di tali modifiche (nel gergo PO, si tratta delle cosiddette stringhe "fuzzy"). Tali stringhe non saranno utilizzate nella traduzione finché non saranno corrette.

• Il pannello inferiore contiene vari strumenti che possono agevolare il lavoro di traduzione, come il contesto delle stringhe circonstanti (solitamente dallo stesso strumento dell'editor oppure dalla stessa pagina di documentazione, quindi potrebbero usare termini simili), commenti di altri traduttori, traduzioni automatiche e un elenco di tutte le altre traduzioni esistenti per quella stringa.

• In alto a destra, il glossario mostra i termini per i quali è stata aggiunta una voce in precedenza e che sono inclusi nella stringa attuale. Ad esempio, se hai deciso insieme ai vostri colleghi traduttori di utilizzare una traduzione specifica per il termine "nodo" in Godot, potete aggiungerla al glossario per assicurare che gli altri traduttori utilizzino la stessa convenzione.

• Il pannello in basso a destra include informazioni sulla stringa sorgente. L'elemento più pertinente è "Posizione della stringa sorgente", il quale punta alla stringa originale su GitHub. Potrebbe essere necessario cercare la stringa nella pagina per individuare essa e il contesto circostante.

Individuazione dei contenuti originali

I file PO sono un elenco ordinato di stringhe sorgenti (msgid) e della loro traduzione (msgstr) e, come predefinito, Weblate presenta le stringhe in quest'ordine. Può quindi essere utile capire come è organizzato il contenuto nei file PO per individuare il contenuto originale e utilizzarlo come riferimento durante la traduzione.

Importante

È fondamentale utilizzare il contesto originale come riferimento durante la traduzione, poiché molte parole hanno diverse possibili traduzioni a seconda del contesto. Una traduzione errata può effettivamente essere dannoso per l'utente e rendere le cose più difficili da capire rispetto a se fossero rimaste in inglese. L'utilizzo del contesto rende anche il lavoro di traduzione molto più semplice e piacevole, poiché puoi vedere direttamente se la traduzione che hai scritto avrà senso nel contesto.

• The editor interface's translation template is generated by parsing all the C++ source code in alphabetical order, so all the strings defined in a given file will be grouped together. For example, if the "source string location" indicates editor/code_editor.cpp, the current string (and the nearby ones) is defined in the editor/code_editor.cpp code file, and is thereby related to the code editors in Godot (GDScript, shaders).

• The online documentation's translation template is generated from the source RST files in the same order as seen in the table of contents, so for example the first strings are from the front page of the documentation. The recommended workflow is therefore to find a unique string corresponding to a page that you want to translate, and then translate all the strings with the same source string location while comparing with the online version of that page in English. An example of source string location could be getting_started/step_by_step/nodes_and_scenes.rst for the page Nodi e Scene.

• The class reference's translation template is generated from the source XML files in alphabetical order, which is also the same as the order of the table of contents for the online version. You can therefore locate the source string corresponding to the brief description of a given class to find the first string to translate and all other descriptions from that class should be in the subsequent strings on Weblate. For example, the descriptions for the Node2D class would have the source string location doc/classes/Node2D.xml.

A handy tool to locate specific pages/classes is to use Weblate's advanced search feature, and especially the "Location strings" query (which can also be used with the location: token, e.g. location:nodes_and_scenes.rst):

Nota

When a given source string is used in multiple source locations, they will all be concatenated into one. For example, the above location:nodes_and_scenes.rst query would land first on the "Introduction" source string which is used in dozens of pages, including some that come before nodes_and_scenes.rst in the template. Clicking the "Next" button then brings us to the "Scene and nodes" title string displayed above. So it may happen that a given paragraph or section title is not at the location you'd expect it when reading the online version of a page.

Rispetto della sintassi di markup

Ogni risorsa di traduzione ha origine da un formato di codice sorgente diverso ed è importante avere qualche nozione sul linguaggio di markup utilizzato per ogni risorsa, per evitare di creare errori di sintassi nelle traduzioni.

Interfaccia dell'editor (C++)

Le traduzioni dell'editor provengono da stringhe in C++ e possono usare:

• C format specifiers such as %s (a string) or %d (a number). These specifiers are replaced by content at runtime, and should be preserved and placed in your translation where necessary for it to be meaningful after substitution. You may need to refer to the source string location to understand what kind of content will be substituted if it's not clear from the sentence. Example (%s will be substituted with a file name or path):

  # PO file:
  "There is no '%s' file."
  
  # Weblate:
  There is no '%s' file.
  

• C escape characters such as \n (line break) or \t (tabulation). In the Weblate editor, the \n characters are replaced by ↵ (return) and \t by ↹. Tabs are not used much, but you should make sure to use line breaks in the same way as the original English string (Weblate will issue a warning if you don't). Line breaks might sometimes be used for vertical spacing, or manual wrapping of long lines which would otherwise be too long especially in the editor translation). Example:

  # PO file:
  "Scene '%s' is currently being edited.\n"
  "Changes will only take effect when reloaded."
  
  # Weblate:
  Scene '%s' is currently being edited.↵
  Changes will only take effect when reloaded.
  

Nota

Solo l'ordine logico dei caratteri conta, nel testo da destra a sinistra, gli identificatori di formato potrebbero essere visualizzati come s%.

Documentazione online (RST)

Le traduzioni della documentazione provengono da file reStructuredText (RST), che usano anche la loro sintassi di markup per stilizzare il testo, creare collegamenti interni ed esterni, ecc. Ecco alcuni esempi:

# "development" is styled bold.
# "Have a look here" is a link pointing to https://docs.godotengine.org/en/latest.
# You should translate "Have a look here", but not the URL, unless there is
# a matching URL for the same content in your language.
# Note: The `, <, >, and _ characters all have a meaning in the hyperlink
# syntax and should be preserved.

Looking for the documentation of the current **development** branch?
`Have a look here <https://docs.godotengine.org/en/latest>`_.

# "|supported|" is an inline reference to an image and should stay unchanged.
# "master" uses the markup for inline code, and will be styled as such.
# Note: Inline code in RST uses 2 backticks on each side, unlike Markdown.
# Single backticks are used for hyperlinks.

|supported| Backwards-compatible new features (backported from the ``master``
branch) as well as bug, security, and platform support fixes.

# The :ref: Sphinx "role" is used for internal references to other pages of
# the documentation.
# It can be used with only the reference name of a page (which should not be
# changed), in which case the title of that page will be displayed:

See :ref:`doc_ways_to_contribute`.

# Or it can be used with an optional custom title, which should thus be translated:

See :ref:`how to contribute <doc_ways_to_contribute>`.

# You may encounter other Sphinx roles, such as :kbd: used for shortcut keys.
# You can translate the content between backticks to match the usual key names,
# if it's different from the English one.

Save the scene. Click Scene -> Save, or press :kbd:`Ctrl + S` on Windows/Linux
or :kbd:`Cmd + S` on macOS.

Vedi anche

Consulta reStructured Text primer di Sphinx per una breve panoramica del linguaggio di markup che potresti trovare nelle stringhe sorgente. In particolare, potresti incontrare il markup in riga (grassetto, corsivo, codice in riga) e il markup dei collegamenti ipertestuali interni ed esterni.

Riferimento classi (BBCode)

Il riferimento classi è documentato nel repository principale di Godot usando file XML, e con markup tipo BBCode per lo stile e i riferimenti interni.

Alcuni dei tag utilizzati provengono dal BBCode originale (come [b]grassetto[/b] e [i]corsivo[/i]), mentre altri sono specifici di Godot e utilizzati per funzionalità avanzate, come codice in riga ([code]true[/code]), collegamenti ad altre classi ([Node2D]) o a proprietà in certe classi ([member Node2D.position]), o per blocchi di codice su più righe. Esempio:

Returns a color according to the standardized [code]name[/code] with [code]alpha[/code] ranging from 0 to 1.
[codeblock]
red = ColorN("red", 1)
[/codeblock]
Supported color names are the same as the constants defined in [Color].

Nell'esempio precedente, [code]name[/code], [code]alpha[/code], e [Color] dovrebbero non essere tradotti, poiché si riferiscono rispettivamente a nomi di argomenti e a una classe dell'API di Godot. Similmente, il contenuto di [codeblock] non dovrebbe essere tradotto, poiché ColorN è una funzione dell'API Godot e "red" è uno dei colori nominati che supporta. Al massimo, puoi tradurre il nome della variabile che contiene il risultato (red = ...).

Nota anche che nell'XML, ogni riga è un paragrafo, quindi non dovresti aggiungere interruzioni di riga se non fanno parte della traduzione originale.

Vedi anche

Vedi la nostra documentazione per gli scrittori del riferimento classi per la lista di tag tipo BBCode che sono usati in tutto il riferimento classi.

Traduzione e test offline

Sebbene consigliamo di usare l'interfaccia Weblate per scrivere le traduzioni, hai anche la possibilità di scaricare il file PO localmente per tradurlo con la tua applicazione di modifica PO preferita, come Poedit o Lokalize.

Per scaricare il file PO localmente, vai alla panoramica delle traduzioni per la tua lingua e seleziona la prima voce nel menu "File":

Dopo aver terminato una serie di modifiche, usa la voce "Carica traduzione" in quello stesso menu e seleziona il tuo file. Scegli "Aggiungi come traduzione" per la modalità di caricamento del file.

Nota

Se è passato molto tempo tra il download del file PO e il caricamento della versione modificata, c'è il rischio di sovrascrivere le traduzioni create da altri collaboratori nel frattempo. Ecco perché consigliamo di utilizzare l'interfaccia online, in modo da lavorare sempre sull'ultima versione.

Se vuoi testare i cambiamenti localmente (specialmente per la traduzione dell'editor), puoi usare il file PO scaricato e compilare Godot da sorgente.

Rinomina il file PO di traduzione dell'editor in <lang>.po (ad esempio eo.po per l'esperanto) e inseriscilo nella cartella editor/translations/ (GitHub).

Puoi anche testare le modifiche al riferimento classi allo stesso modo rinominando il file PO in modo simile e inserendolo nella cartella doc/translations/ (GitHub).

Localizzare le immagini nella documentazione

La documentazione online include molte immagini, che possono essere screenshot dell'editor di Godot, grafici personalizzati, o qualsiasi altro tipo di contenuto visivo. Alcune di esse includono del testo e potrebbero quindi essere rilevanti da localizzare nella tua lingua.

Questa parte non è gestita tramite Weblate, ma direttamente sul repository Git godot-docs-l10n dove le traduzioni della documentazione sono sincronizzate da Weblate.

Nota

Il flusso di lavoro non è dei più semplici e richiede una certa conoscenza di Git. Abbiamo in programma di lavorare su uno strumento web semplificato che potrebbe essere usato per gestire la localizzazione delle immagini in modo conveniente, astraendo questi passaggi.

Per tradurre un'immagine, dovresti prima individuarla nella documentazione originale in inglese. Per fare ciò, sfoglia la pagina corrispondente nella documentazione, ad esempio Prima occhiata all'interfaccia di Godot. Clicca sul link "Edit on GitHub" in alto a destra:

Su GitHub, clicca sull'immagine che vuoi tradurre. Se applicabile, clicca su "Download" per scaricarla localmente e modificarla con uno strumento di modifica delle immagini. Prendi nota del percorso completo all'immagine perché sarà necessario in seguito (qui getting_started/step_by_step/img/project_manager_first_open.png).

Crea la tua versione localizzata dell'immagine, modificando quella inglese, o facendo uno screenshot dell'editor con la tua lingua, se è una schermata dell'editor. Alcune immagini potrebbero anche avere file sorgente disponibili in formato SVG; per verificarlo, puoi sfogliare la cartella img/ che le contiene.

Assegna alla tua immagine localizzata lo stesso nome di quella originale, ma con il codice della lingua aggiunto prima dell'estensione, ad esempio project_manager_first_open.png diventerebbe project_manager_first_open.it.png per la localizzazione italiana.

Infine, su godot-docs-l10n, ricrea la stessa struttura di cartelle dell'immagine originale nella sottocartella images (GitHub), e inseriscici la tua immagine tradotta. Nel nostro esempio, il risultato finale dovrebbe essere images/getting_started/step_by_step/img/project_manager_first_open.it.png.

Ripeti lo stesso processo per altre immagini e crea una Pull Request.