Traduzione dei contenuti¶

Sebbene l'inglese sia una lingua molto comune per gli sviluppatori di software, ci sono molti sviluppatori che non parlano l'inglese o non lo parlano correntemente. Si tratta di un problema di accessibilità per gli sviluppatori, per cui vogliamo fornire la nostra documentazione nel maggior numero di lingue possibile.

Sfortunatamente, il team centrale di BeeWare è, per la maggior parte, monolingue inglese. Abbiamo bisogno del vostro aiuto per tradurre la nostra documentazione in altre lingue.

Utilizziamo Weblate per gestire le nostre traduzioni. Weblate è uno strumento che ci permette di trattare ogni paragrafo di contenuto della nostra documentazione come un elenco di cose da fare, da elaborare una alla volta.

Utilizziamo DeepL per la traduzione automatica per produrre una prima bozza di traduzione. Le traduzioni automatiche sono tutt'altro che perfette, ma di solito sono sufficienti come prima bozza. L'aspettativa è che queste traduzioni automatiche vengano modificate, riviste e migliorate se necessario.

Contribuire alle traduzioni¶

Traduci contenuto

Come iniziare a tradurre¶

Se vuoi contribuire agli sforzi di traduzione di BeeWare, devi avere un account su Weblate. Crea un nuovo account se non ne hai ancora uno; poi facci sapere che sei interessato a dare una mano con le traduzioni.

Ci sono due opzioni per farci sapere che volete aiutarci con le traduzioni:

Se sei su Discord, unisciti al server BeeWare e vai al canale #translations.
Se non sei su Discord, puoi creare un nuovo problema sul repository BeeWare.

In entrambi i casi, lasciate un messaggio con le seguenti informazioni:

Il vostro nome utente Weblate
La lingua verso la quale si intende tradurre il contenuto

Una volta ottenute queste informazioni, ti aggiungeremo alla squadra.

Aggiunta di una nuova traduzione¶

Se la lingua che si intende aiutare non esiste già, sono necessari alcuni passaggi aggiuntivi prima di poter iniziare:

Creare il file /docs/mkdocs.language-code.yml, con il contenuto specifico della lingua.
Aggiornare tox.ini per includere i comandi di compilazione della nuova lingua.
Aggiornare /docs/config.yml per includere la lingua sotto extra: alternate:.

Di seguito vengono illustrate le modifiche necessarie, utilizzando come esempio il tedesco; una traduzione in tedesco esiste già; sostituire i riferimenti al tedesco, a de o ad altri contenuti per la lingua a cui ci si rivolge.

Un nuovo file di configurazione di MkDocs¶

Per prima cosa, creare un nuovo file chiamato mkdocs.de.yml nella cartella docs, con il seguente contenuto:

INHERIT: config.yml
site_name: BeeWare Dokumentation
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  translation_type: machine

Ecco cosa succede in questo file:

Questo file eredita il contenuto della configurazione da config.yml.
Il valore site_name viene tradotto.
Il valore site_url è l'URL del sito del progetto, seguito dal codice della lingua.
La docs_dir dovrebbe essere il codice della lingua.
Il valore tema: language: dovrebbe essere il codice della lingua, come specificato dal tema MkDocs Material. Per la maggior parte delle lingue, questo sarà uguale al codice della lingua docs_dir; ma per alcune (in particolare le lingue con varianti di locale come zh_CN), ci sono differenze.
L'opzione extra: translation_type: dovrebbe essere machine fino a quando la traduzione non raggiunge il 100% per la prima volta, a quel punto dovrebbe essere human. Si tornerà a machine da human se si scende sotto il 90%.

Aggiornare `tox.ini¶

È necessario apportare diverse modifiche al file tox.ini.

Si aggiunge quanto segue:

Il nuovo flag di ambiente del codice della lingua alla riga di intestazione che inizia con [testenv:docs, con il codice della lingua preceduto da un -, senza spazi inclusi, ad esempio -de.
Il nuovo codice linguistico esclude il primo comando, che inizia con !lint, preceduto da -!, senza spazi, ad esempio -!de.
Il codice della nuova lingua alla fine della riga che inizia con translate : build_po_translations.
Il codice della nuova lingua alla fine della riga che inizia con translate : update_machine_translations.
Un nuovo comando, che inizia, ad esempio, con de : build_md_translations per il tedesco, dopo gli altri comandi specifici per la lingua esistenti, che abbina il contenuto di tali comandi con il nuovo codice della lingua.
Il nuovo codice della lingua alla fine della riga che inizia con all,serve :.

Aggiornare `config.yml¶

Aggiungere la lingua a config.yml, in modo che appaia nel selettore della lingua nell'intestazione. Trovare la sezione che inizia con extra: e quindi individuare la sottosezione che inizia con alternate:. Per il tedesco, si dovrebbe aggiungere quanto segue:

    - name: Deutsch
      link: /de/
      lang: de

Il nome della lingua deve essere tradotto nella lingua. Il link deve includere le /.

La nuova lingua è ora pronta per iniziare la traduzione.

Linee guida per la traduzione¶

Una volta aggiunti al team, è il momento di accedere a Weblate e iniziare a tradurre le stringhe.

Il tono rispetto alla traduzione parola per parola¶

È più importante mantenere il tono del testo inglese che sforzarsi di tradurre parola per parola. Cerchiamo di essere amichevoli e un po' colloquiali nei nostri contenuti; cercate di mantenere questo spirito nelle vostre traduzioni.

Se il testo inglese contiene un forte idioma inglese, non sentitevi obbligati a mantenerlo, se esiste un analogo nella vostra lingua che funzionerebbe altrettanto bene. Se il termine o la frase del testo inglese è un termine particolarmente idiomatico o gergale, non abbiate paura di dirci che dovremmo prendere in considerazione una modifica. Anche per chi parla inglese, le espressioni idiomatiche e gergali possono creare difficoltà. A volte è necessario modificare il testo inglese per renderlo più semplice sia per i traduttori che per i lettori.

Devo tradurlo?¶

I seguenti elementi non devono essere tradotti o aggiornati:

Comandi. Ad esempio, in "You should run `briefcase create`", solo "You should run" deve essere tradotto.
Spazi di nomi, come i nomi di classi, metodi o attributi.
Link URL. I link Markdown standard dovrebbero apparire in Weblate come [Link text]{1}, dove 1 è la posizione del link nella stringa con riferimento ad altri possibili link. Se l'URL completo è incluso nella stringa, come [Link text](https://example.com), l'URL deve essere saltato per la traduzione.
Link di riferimento contenenti nomi di classi, metodi o attributi. Questi dovrebbero essere lasciati così come sono, compresi i backtick. Tutte le parti del link di esempio qui mostrato non verrebbero tradotte.
```
[`Class.attribute`][Class.attribute]
```
Il contenuto del link di un link di riferimento. Ad esempio, link-content verrebbe saltato nel seguente caso:
```
[Link text][link-content]
```
Direttive Jinja. Si tratta di qualsiasi contenuto avvolto all'interno di due coppie di parentesi graffe corrispondenti, o di una coppia corrispondente di parentesi graffe singole con segni di percentuale all'interno di ciascuna estremità. Nota: l'inclusione di un esempio della sintassi provoca il tentativo di renderla da parte del plugin Macros; si veda la documentazione di Macros per gli esempi.
Ancore personalizzate. Si trovano dopo le intestazioni o sopra alcuni contenuti e sono formattati come { #ancora }.
Sintassi dell'ammonizione. Nell'esempio seguente, la parola "ammonizione" non deve essere tradotta. Questo vale per tutti gli stili di ammonizione, comprese le note, gli avvertimenti, ecc. Vedere la sezione successiva per informazioni sulla traduzione del resto del contenuto.
```
/// admonition | Page Title

Content.

///
```
Backticks. Sono destinati a rimanere come backtick; sono usati per formattare sia il codice in linea che i blocchi di codice.
La sintassi per includere contenuti esterni. Si tratta di qualsiasi cosa sulla stessa riga di -8<-, o sulle righe tra due -8<- su righe separate.

Le seguenti voci dovrebbero essere tradotte:

Testo del collegamento. Nella sintassi dei link, il testo viene prima dell'URL ed è racchiuso tra parentesi, come in [Link text](URL). I link Markdown standard dovrebbero apparire in Weblate come [Testo del link]{1}, dove 1 è la posizione del link nella stringa con riferimento ad altri possibili link.
Testo del link di riferimento. Ad esempio, Link text verrebbe tradotto come segue:
```
[Link text][link-content]
```
Titoli e contenuti delle ammonizioni. Nell'esempio precedente, "Titolo della pagina" e "Contenuto" devono essere tradotti.

Weblate¶

Utilizziamo Weblate per la traduzione dei contenuti. Quando aggiungiamo una nuova traduzione, usiamo DeepL per la traduzione automatica per produrre un primo passaggio di traduzioni. Ciò significa che, in genere, il contenuto che tradurrete è già tradotto automaticamente. L'aspettativa è che il traduttore riveda, modifichi e migliori la traduzione automatica esistente.

Weblate elabora tutto su base stringa per stringa. Le modifiche vengono raggruppate e ogni due ore viene inviato un commit di massa con tutte le stringhe modificate in quell'intervallo. Quindi, potrebbero volerci un paio d'ore prima che le modifiche vengano visualizzate sul sito web, ma si può prevedere che l'aggiornamento venga visualizzato entro quattro ore.

Se dopo tale periodo le modifiche non sono ancora state pubblicate, la causa probabile è un errore di markup che ha causato un errore nella compilazione dei documenti per quella lingua. Qualsiasi problema di markup in una stringa bloccherà la pubblicazione dell'intera traduzione. È possibile tenere d'occhio la pagina di compilazione della propria lingua per verificare se la compilazione è stata completata con successo. Il link ha un formato simile a questo link alla pagina di compilazione francese https://app.readthedocs.org/projects/beewareorg/; modifica il codice della lingua con quello della tua lingua per visualizzare la pagina di compilazione appropriata. Verrà mostrato lo stato della compilazione più recente del sito. Se la compilazione non va a buon fine, consulta il log di compilazione e verifica se riesci a identificare la causa del problema.