# Internazionalizzazione

Flarum dispone di un potente sistema di traduzione (basato sul Traduttore Symfony (opens new window)) che consente all'interfaccia di visualizzare le informazioni praticamente in qualsiasi lingua. Dovresti considerare di sfruttare il traduttore di Flarum mentre sviluppi la tua estensione, anche se non hai intenzione di usarlo in più di una lingua.

Per prima cosa, questo sistema ti consentirà di modificare le informazioni visualizzate dalla tua estensione senza modificare il codice effettivo. Ti darà anche gli strumenti necessari per affrontare in modo efficiente fenomeni come il pluralismo e l'accordo per il genere. E non si sa mai: potrebbe tornare utile in seguito se decidi di aggiungere più lingue e rendere la tua estensione disponibile agli utenti di tutto il mondo!

Questa guida ti mostrerà come creare unf ile locale contenente traduzioni per la tua estensione, e come utilizzare il traduttore per accedere a tali risorse dall'interno del codice. Imparerai come affrontare traduzioni più complesse che coinvolgono variabili e tag HTML, così come le pluralizzazioni ed i generi.

Descriveremo anche i formati standardda seguire nello sviluppo di traduzioni per Flarum, e vi daremo alcuni consigli che può aiutarti a rendere le tue risorse più facili da localizzare. Ma prima, iniziamo con una panoramica di come Flarum assegna la priorità alle risorse durante la visualizzazione dell'output per un'estensione di terze parti.

# Come traduce Flarum

A differenza delle estensioni in bundle di Flarum & mdash; che vengono tradotti utilizzando risorse aggiunte da pacchetti di lingue; un'estensione di terze parti deve fornire tutte le proprie traduzioni. In qualità di sviluppatore Flarum, spetterà a te ottenere e mantenere le risorse per ogni lingua che desideri che la tua estensione supporti.

Di norma, un sito Flarum può visualizzare solo le traduzioni corrispondenti ai language pack che sono stati installati su quel sito. Ma Flarum farà del suo meglio & mdash; entro questa limitazione & mdash; per rendere l'output della tua estensione in una sorta di linguaggio leggibile dall'utente:

  1. Inizierà cercando una traduzione nella lingua di visualizzazione preferita dall'utente.
  2. Se non riesce a trovarne una, cercherà una traduzione nella lingua predefinita del forum.
  3. Come ultimo tentativo, cercherà una traduzione inglese "generica" dell'output.
  4. Se nessuno dei precedenti è disponibile, si arrenderà e visualizzerà una chiave di traduzione.

Poiché le traduzioni in inglese potrebbero essere l'unica cosa che si frappone tra gli utenti del forum e le antiestetiche chiavi di traduzione, consigliamo vivamente di includere un set completo di risorse in inglese con ogni estensione. (Dovrai anche includere risorse in inglese se desideri elencare la tua estensione su Flarum Marketplace.)

# File Locali

Le risorse linguistiche di Flarum utilizzano l'estensione ed il formato file YAML (opens new window). I file delle impostazioni locali per un'estensione di terze parti devono essere archiviati nella cartella locale dell'estensione. Ogni file locale deve essere denominato utilizzando l'estensione ISO 639-1 (opens new window) per la lingua che contiene. Ad esempio, un file contenente traduzioni francesi dovrebbe essere denominato "fr.yml".

TIP

Se desideri fornire supporto per una lingua specifica, puoi aggiungere un trattino basso seguito da un codice regione ISO 3166-1 alpha-2 (opens new window); il nome del file per il francese parlato in Canada, ad esempio, sarebbe "fr_CA.yml". Ma dovresti assicurarti di includere un file locale contenente traduzioni "generiche" per la stessa lingua, così Flarum avrà qualcosa su cui ripiegare nel caso in cui un utente specifichi una lingua che non hai fornito.

Lo scheletro di estensione include anche il template locale/en.yml dove puoi inserire le traduzioni in inglese della tua estensione. Se si desidera aggiungere risorse per un'altra lingua o locale, è sufficiente duplicare il modello e assegnargli un nome file appropriato. Quindi apri il file e inizia ad aggiungere le tue traduzioni!

# Aggiungere chiavi

Ogni traduzione nel file locale deve essere preceduta da una chiave, che utilizzerai come ** identificatore ** per quella traduzione. La chiave ID dovrebbe essere in snake_case e seguito da due punti e uno spazio, come mostrato di seguito:

sample_key: Questa è una traduzione di esempio.

Puoi anche utilizzare le chiavi per ** dare spazi ai nomi ** per le tue traduzioni.. Per i principianti, la prima riga del file locale dovrebbe consistere in una singola chiave che raccoglie tutte le traduzioni per la tua estensione in un unico spazio. Questa chiave dovrebbe corrispondere esattamente al nome della cartella in cui risiede l'estensione — kebab-case.

È possibile utilizzare chiavi aggiuntive per dividere lo spazio dei nomi dell'estensione in gruppi. Ciò è utile quando si desidera organizzare le traduzioni in base a dove vengono visualizzate nell'interfaccia utente, ad esempio. Queste chiavi di spaziatura dei nomi intermedie dovrebbero sempre essere in snake_case.

Ogni chiave di spaziatura dei nomi dovrebbe anche essere seguita da due punti. Le chiavi devono essere nidificate secondo il formato struttura YAML, aggiungendo due spazi di rientro per ogni livello nella gerarchia. Metti tutto insieme ed il file locale tutorial per iniziare dovrebbe assomigliare a questo:

acme-hello-world:                # Namespacing for the extension; unindented.
  alert:                         # Namespacing for alerts; indented 2 spaces.
    hello_text: "Hello, world!"  # Identifier/translation; indented 4 spaces.

Una volta che hai queste informazioni a posto, puoi formare la ** chiave di traduzione completa ** che utilizzerai per accedere a una traduzione elencandone le chiavi in ordine dallo spazio dei nomi dell'estensione a un identificatore, con i punti come delimitatori. Ad esempio, la chiave di traduzione completa per "Hello, world!" sarebbe:

'acme-hello-world.alert.hello_text'

Questo è davvero tutto ciò che devi sapere sui meccanismi di creazione delle chiavi. Tieni presente, tuttavia, che esiste un formato standard che gli sviluppatori devono seguire quando creano le risorse linguistiche per Flarum. Le regole per il namespacing delle traduzioni e assegnare un nome ad chiavi ID possono essere trovati nell'appencice A.

# Aggiungere traduzioni

Gli esempi nella sezione precedente ti hanno già fornito le basi:digiti una chiave ID — seguito da due punti e uno spazio — quindi digiti la traduzione. Facile! Ora vorremmo solo aggiungere alcuni dettagli che ti aiuteranno a gestire traduzioni più lunghe e complesse.

Virgolette

Avrai notato che solo una delle due traduzioni di esempio nella sezione precedente era racchiusa tra virgolette. Generalmente non è necessario delimitare le traduzioni in questo modo. Tuttavia, dovresti utilizzare ** virgolette doppie ** per racchiudere qualsiasi traduzione che includa uno o più dei seguenti caratteri:

`  !  @  #  %  &  *  -  =  [  ]  {  }  |  :  ,  <  >  ?

Poiché Flarum utilizza parentesi graffe e parentesi angolari per indicare i le variabili ed i tag HTML, rispettivamente, è ovvio che qualsiasi traduzione che includa tali variabili dovrà essere racchiusa tra virgolette doppie.

Inoltre, dovresti usare ** virgolette singole ** per racchiudere qualsiasi traduzione che includa una o più virgolette doppie (") o backslash (\). Questa regola ha la precedenza! Quindi, se una traduzione dovesse includere sia le virgolette doppie che uno o più caratteri dalla lista sopra — come questo esempio, in cui una variabile è compensata da virgolette — andrebbe racchiuso tra * virgolette singole *.

# Blocchi letterali

Quando è necessario che una traduzione appaia come più di una singola riga di testo, la traduzione deve essere aggiunta come un ** blocco letterale **. Inserisci una barra verticale (|) dove normalmente inizieresti la traduzione, quindi aggiungi la traduzione sotto il tasto ID, facendo rientrare ogni riga di altri due spazi:

literal_block_text: |
  Queste righe verranno visualizzate come mostrato qui, interruzioni di riga e tutto il resto.

     Anche il rientro extra viene mantenuto: questa riga sarà rientrata di 4 spazi!

  Le virgolette non sono necessarie, anche quando il blocco contiene caratteri speciali.

Il blocco letterale termina con l'ultima riga da rientrare di almeno due spazi in più rispetto alla chiave ID. Le virgolette non sono necessarie perché il blocco è effettivamente delimitato da questi due spazi extra di rientro.

Le principali risorse linguistiche di Flarum utilizzano blocchi letterali principalmente per il contenuto del corpo dell'email.

# Riferimenti chiave

Non è raro utilizzare la stessa porzione di testo in più di una posizione o contesto. Supponiamo che tu voglia che la tua estensione visualizzi la frase "Modifica elementi" in due posizioni nell'interfaccia utente:

  • Come un ** pulsante ** su cui gli utenti possono fare clic quando desiderano modificare alcune cose
  • Come il ** titolo ** di una finestra di dialogo visualizzata quando gli utenti fanno clic su quel pulsante

Il tuo istinto potrebbe essere quello di aggiungere un'unica traduzione — chiuamiamola "edit_stuff" — e usiamo quella chiave ID due volte nel tuo codice. Questo approccio è efficiente, ma manca di flessibilità: in alcune lingue, potrebbe non essere possibile utilizzare la stessa frase sia per il pulsante che per il titolo della finestra di dialogo! Un modo migliore sarebbe definire * due * chiavi da utilizzare nel codice, quindi impostarle entrambe per fare riferimento alla stessa traduzione, in questo modo:

edit_stuff_button: => edit_stuff    # Utilizzato nel codice che crea il pulsante.
edit_stuff_title: => edit_stuff     # Utilizzato nel codice che crea la finestra di dialogo.

edit_stuff: Edit Stuff              # Non utilizzato nel codice.

È possibile impostare una chiave in modo che faccia riferimento ad un'altra sostituendo la sua traduzione con un segno di uguale (=), un segno di maggiore (>), e uno spazio, seguito dalla chiave di traduzione completa a cui fare riferimento. Quando l'estensione è installata, il compilatore di Flarum risolverà questi riferimenti per creare un set completo di traduzioni che può usare.

C'è altro da dire sulla referenziazione — per prima cosa, abbiamo completamente ignorato il problema dello spazio dei nomi nell'esempio sopra! E ti starai chiedendo perché abbiamo suggerito di creare tre chiavi quando due sarebbero sufficienti. Per una spiegazione, vedere le regole per la riutilizzazione di traduzioni nell'appendice A.

# Utilizzare il traduttore

Dopo aver aggiunto una traduzione al file delle impostazioni locali, con spazi dei nomi e chiavi di identificazione appropriati, è possibile utilizzare l'estensione app.translator.trans() per fare riferimento a tale traduzione nel codice. Per esempio il file js/forum/src/index.js Tutorial per iniziare potrebbe finire per assomigliare a questo:

app.initializers.add('acme-hello-world', function() {
  alert(app.translator.trans('acme-hello-world.alert.hello_text'));
});

Questo mostra il metodo di traduzione di base, senza campanelli o fischietti allegati. Di seguito troverai esempi di traduzioni più complesse che coinvolgono variabili e tag HTML. (Tieni presente che abbiamo omesso lo spazio dei nomi nei seguenti esempi per mantenerli semplici; se guardi il codice effettivo, troverai che le traduzioni hanno una spaziatura dei nomi appropriata in base al formato standard.)

# Includere Variabili

Puoi includere variabili nelle traduzioni. Ad esempio, diamo un'occhiata al codice che crea il primo elemento nel menu a discesa dei risultati di ricerca di Flarum (opens new window). Questo pulsante cita la query di ricerca inserita dall'utente e altre informazioni che vengono passate al traduttore insieme alla chiave di traduzione, come parametro aggiuntivo:

{LinkButton.component({
  icon: 'search',
  children: app.translator.trans('all_discussions_button', {query}),
  href: app.route('index', {q: query})
})}

Una variabile corrispondente nella traduzione consente al traduttore di sapere dove inserire la variabile:

all_discussions_button: 'Search all discussions for "{query}"'

Poiché le parentesi graffe vengono utilizzate per indicare le variabili, la traduzione nel suo insieme deve essere racchiusa in Virgolette. Normalmente, vengono utilizzate le virgolette doppie; ma poiché questa particolare traduzione utilizza le virgolette doppie per impostare la query di ricerca, la regola delle virgolette singole ha la precedenza.

# Aggiungere tag HTML

L'estrazione delle traduzioni dall'HTML può rappresentare una sfida unica: come gestisci gli elementi HTML che influenzano solo una parte della frase? Fortunatamente, Flarum ti offre un modo per aggiungere tag alle tue traduzioni.

Si inizia aggiungendo una chiave ai parametri di ogni elemento che si desidera venga gestito dal traduttore. Lo snippet seguente — preso da Modifica gruppi modali (opens new window) dell'interfaccia di amministrazione — mostra una chiave di traduzione accompagnata da un oggetto e da un elemento.

<div className="helpText">
  {app.translator.trans('icon_text', {
    a: <a href="https://fortawesome.github.io/Font-Awesome/icons/" tabindex="-1"/>
  })}
</div>

Nota che ogni parametro è definito utilizzando un singolo tag HTML, con una barra aggiunta prima della parentesi angolare di chiusura. È quindi possibile utilizzare tag di apertura e chiusura in stile HTML nel file delle impostazioni locali per specificare quale parte della traduzione è interessata da ciascun elemento. Ancora una volta, sono richieste virgolette doppie. Puoi vedere che non tutti i tag vengono passati come argomenti, solo quelli che hanno attributi.

icon_text: "Enter the name of any <a>FontAwesome</a> icon class, <em>without</em> the <code>fa-</code> prefix."

Ovviamente puoi dare a un parametro il nome che preferisci; puoi utilizzare <fred> e </fred> per racchiudere il testo del tuo link se ti può far piacere! Tuttavia, ti consigliamo di rimanere il più vicino possibile ai tag HTML effettivi rappresentati, in modo che i tuoi localizzatori saranno in grado di capire cosa sta succedendo.

I localizzatori possono riordinare gli elementi secondo necessità e persino scegliere di omettere i tag se lo desiderano. Ma non possono aggiungere tag propri: il traduttore ignorerà semplicemente qualsiasi tag in stile HTML che non corrisponde a un parametro definito correttamente nel codice.

# Gestione della pluralizzazione

A volte, potrebbe essere necessario fornire versioni alternative di una traduzione per consentire la pluralizzazione di una parola o frase. Questo viene fatto usando il metodo app.translator.transChoice()per passare la chiave di traduzione; insieme a una variabile che imposta le condizioni per la pluralizzazione al traduttore.

const remaining = this.minPrimary - primaryCount;
return app.translator.transChoice(
  'choose_primary_placeholder',
  remaining,
  { count: remaining }
);

Questo esempio è tratto da Scegli tag modali (opens new window) dell'omonima estensione, dove indica all'utente quanti altri tag primari possono essere selezionati. Nota che la variabile remaining viene passato al traduttore ** due volte **. In primo luogo, sembra lo stesso, per condizionare la pluralizzazione della parola "tag". Quindi appare di nuovo come valore del parametro count, che il traduttore può utilizzare per inserire quel valore nella traduzione.

Quando il metodo app.translator.transChoice() viene richiamato, il traduttore esegue la scansione della traduzione per una variante che corrisponde al tipo di pluralizzazione richiesta dal valore della variabile. Queste varianti devono essere elencate in serie, prima in forma singolare, poi in forme plurali in ordine di grandezza crescente e separati utilizzando la linea verticale ("|"). Ecco la traduzione in inglese del codice sopra:

choose_primary_placeholder: "Choose a primary tag|Choose {count} primary tags"

Ovviamente l'inglese ha solo due varianti: singolare o plurale. Dovrai fornire varianti aggiuntive quando crei traduzioni per una lingua che ha più di una forma plurale. Se hai bisogno di informazioni dettagliate sul numero di varianti richieste per una lingua o l'ordine in cui dovrebbero essere elencati, fai riferimento alle regole di pluralizzazione (opens new window) che Flarum usa per mappare la variabile alle forme plurali.

# Avere a che fare con i generi

Il supporto per il genere grammaticale sarà aggiunto in una futura versione di Flarum. Istruzioni dettagliate verranno fornite qui una volta che la funzionalità sarà disponibile.

# Traduzione lato server

La traduzione è generalmente gestita dal client front-end di Flarum. Tuttavia, puoi usare le traduzioni nel tuo codice PHP se necessario.

Innanzitutto, dovrai ottenere un'istanza della classe Flarum\Locale\Translator. E può essere fatto in diversi modi:

$translator = app('translator');
$translator = app('Flarum\Locale\Translator');
$translator = app(Translator::class); // dovrai importare la classe con 'use' per questo

Quindi, l'API è simile alla classe JavaScript Translator. Puoi usare $translator->transcome useresti app.translator.trans in JavaScript. Puoi saperne di più sui metodi del traduttore su documentazione del traduttore Symfony (opens new window).

# Registrazione delle impostazioni locali

C'è un'ultima cosa che devi fare prima che Flarum possa usare le tue traduzioni. Devi registrarle. Fortunatamente, Flarum lo rende abbastanza facile. Aggiungi quanto segue al tuo file extend.php:

new Extend\Locales(__DIR__ . '/locale'),

# Appendice A: formato chiave standard

Le seguenti linee guida sono state create per l'uso nelle estensioni principali in bundle di Flarum. Il loro scopo è garantire che le chiavi di traduzione siano organizzate e denominate in modo coerente, in modo che i localizzatori di Flarum siano in grado di creare e mantenere language pack di alta qualità con un minimo di difficoltà. Gli sviluppatori che desiderano contribuire allo sviluppo di Flarum devono seguire queste linee guida. Gli sviluppatori di terze parti si troverebbero meglio seguendoli, così i localizzatori Flarum esperti che si occupano della traduzione di estensioni di terze parti si troveranno a lavorare in un ambiente familiare.

# Namespacing delle Traduzioni

Tutte le traduzioni devono essere organizzate in categorie, utilizzando chiavi di spaziatura dei nomi disposte in un massimo di ** tre ** livelli. Ogni livello fornisce ai localizzatori un bit importante di informazioni su * dove viene utilizzata la traduzione: *

# ➡ La chiave di primo livello indica * quale componente utilizza la traduzione *.

La spaziatura dei nomi per le chiavi di traduzione utilizzate nei componenti Flarum ufficiali, comprese le estensioni in bundle, deve corrispondere al nome del file delle impostazioni locali del language pack per il componente in questione. Gli spazi dei nomi per i componenti non di estensione di Flarum sono fissati come mostrato di seguito:

core:        # Traduzioni usate dal core di Flarum
validation:  # Traduzioni usate dal validatore di Laravel

Le chiavi di traduzione utilizzate in un'estensione o incluse in qualsiasi estensione di terze parti, devono avere una spaziatura dei nomi che utilizza il nome dell'estensione in vendor-package dove i prefissi flarum- e flarum-ext- vengono rimossi da package (es, flarum-tags per l'estensione Tag e foo-bar per l'estensione foo/flarum-ext-bar).

Dovrebbe esserci un solo ** un ** prefisso di primo livello in qualsiasi file locale; e dovrebbe trovarsi nella prima riga.

# ➡ La chiave di secondo livello indica * quale interfaccia utilizza la traduzione *.

Poiché Flarum non ha tutte le interfacce, abbiamo creato un breve elenco di chiavi di secondo livello tra cui scegliere. Abbiamo incluso quelli usati più di frequente nel modello di file locale creato con lo scheletro dell'estensione. Di seguito trovi l'elenco completo, con le spiegazioni:

admin:       # Traduzioni utilizzate dall'interfaccia di amministrazione.
forum:       # Traduzioni utilizzate dall'interfaccia utente del forum.
lib:         # Traduzioni utilizzate da uno dei precedenti.
views:       # Traduzioni utilizzate al di fuori del normale client JS.
api:         # Traduzioni utilizzate nei messaggi emessi dall'API.
email:       # Traduzioni utilizzate nelle email inviate da Flarum.

Le prime quattro chiavi corrispondono all'incirca alle directory contenenti il codice in cui verranno utilizzate le traduzioni. (La maggior parte delle tue chiavi andrà probabilmente in admin o forum.) Le restanti due chiavi sono leggermente diverse: api è per le traduzioni utilizzate nei messaggi emessi dall'API, e email contiene le risorse per tutte le email inviate dal forum.

ref:         # Traduzioni referenziate da più di una chiave.
group:       # Traduzioni utilizzate come gruppi predefiniti.

Queste due chiavi non corrispondono alle interfacce; sono per traduzioni che richiedono una gestione speciale. Spiegheremo come utilizzare ref quando parliamo di riutilizzare le traduzioni. Invece group contiene i nomi dei gruppi predefiniti, che vengono tradotti dal server anziché dal front-end.

# ➡ La chiave di terzo livello indica * quale parte dell'interfaccia utente utilizza la traduzione *.

Le chiavi in questo livello non sono definite così rigidamente. Il loro scopo principale è quello di suddividere l'interfaccia utente in parti gestibili, in modo che i localizzatori possano trovare le traduzioni e vedere da soli come vengono utilizzate dal software. (Le chiavi di terzo livello non vengono utilizzate in ref e group)

Se stai modificando una posizione esistente per aggiungere una nuova impostazione alla pagina Impostazioni,ad esempio dovresti copiare il nostro namespacing in modo che i localizzatori Flarum esperti sappiano a colpo d'occhio esattamente dove vengono visualizzate le nuove traduzioni. Guarda File della lingua inglese (opens new window) per maggiori dettagli.

Se la tua estensione aggiunge una nuova posizione come una nuova finestra di dialogo, dovresti sentirti libero di creare una nuova chiave di terzo livello per il namespacing delle traduzioni che vi andranno. Prenditi un paio di minuti per familiarizzare con il namespacing nei file delle impostazioni locali collegati sopra, quindi crea una nuova chiave che si adatti a quello schema.

Come regola generale, le chiavi di terzo livello dovrebbero essere brevi, non più di una o due parole ed espresse in snake_case. E dovrebbero descrivere la posizione in cui vengono utilizzate le traduzioni.

# Denominazione delle chiavi di identificazione

Come le chiavi di terzo livello, le chiavi identificative devono essere espresse in snake_case. Le chiavi ID devono essere disposte in ordine alfabetico all'interno di ogni nome, in modo che siano facili da trovare per gli sviluppatori. (C'è un'eccezione a questa regola! Le chiavi ID in email dovrebbero essere elencati così come appaiono nel tuo client di posta: prima subject, poi body.)

La tipica chiave ID è composta da due parti; una ** radice ** e un ** suffisso ** ciascuno dei quali può essere omesso in determinate circostanze. Proprio come le chiavi di spaziatura dei nomi indicano ai localizzatori * dove viene utilizzata la traduzione *, ogni parte della chiave ID fornisce un ulteriore bit di informazioni sulla traduzione:

# ➡ Il suffisso indica * come viene utilizzata la traduzione *.

Inizieremo con il suffisso perché è la parte più importante del nome della chiave. Indica ai localizzatori quale tipo di oggetto dovrebbero cercare quando cercano di trovare la traduzione nell'interfaccia. Ad esempio, i suffissi nell'elenco seguente vengono utilizzati per oggetti GUI più o meno correlati alle operazioni dell'utente:

_button:        # Utilizzato per i pulsanti (comprese le voci del menu a discesa).
_link:          # Utilizzato per i collegamenti che non vengono visualizzati graficamente come pulsanti.
_heading:       # Utilizzato per le intestazioni in tabelle ed elenchi.
_label:         # Utilizzato per i nomi dei campi dati, le impostazioni delle caselle di controllo, ecc.
_placeholder:   # Utilizzato per il testo predefinito visualizzato nei campi.

Questi suffissi vengono utilizzati per elementi di testo informativi o descrittivi:

_confirmation:  # Utilizzato per i messaggi visualizzati per confermare un'operazione.
_message:       # Utilizzato per i messaggi che mostrano il risultato di un'operazione.
_text:          # Utilizzato per qualsiasi testo che non sia un messaggio, un titolo o una descrizione comando.
_title:         # Utilizzato per il testo visualizzato come titolo di una pagina o modale.
_tooltip:       # Utilizzato per il testo visualizzato quando l'utente passa con il mouse su qualcosa.

E ci sono due suffissi che vengono usati solo in email:

_body:          # Utilizzato per il contenuto del messaggio di posta elettronica.
_subject:       # Utilizzato per la riga dell'oggetto del messaggio di posta elettronica.

Quanto sopra è un elenco completo dei suffissi disponibili per l'uso nei file delle impostazioni locali. Dovresti fare attenzione a usarli in modo coerente, poiché ciò renderà la vita più facile ai localizzatori. Se ritieni che manchi qualcosa dall'elenco, segnala un problema agli sviluppatori; prenderemo in considerazione l'aggiunta di un nuovo suffisso se la situazione lo richiede.

I suffissi devono essere ** omessi ** nelle chiavi ID per riutilizzare le traduzioni in ref:. Questo perché non puoi essere sicuro che queste traduzioni verranno sempre utilizzate nello stesso contesto. Aggiungere un nuovo contesto significherebbe cambiare il nome della chiave * ovunque sia referenziato * quindi è meglio mantenere queste traduzioni generiche.

# ➡ La radice indica * cosa dice la traduzione *.

Se la traduzione è una frase molto breve, non più lunga di poche parole, potresti volerla usare alla lettera (in snake_case, naturalmente). Se è molto lungo, invece, dovresti provare a ridurla nel minor numero di parole possibile.

In alcuni casi, il riepilogo può essere sostituito da una descrizione della funzione dell'oggetto. Questo è comunemente visto nei pulsanti. Il pulsante che invia un modulo dovrebbe essere identificato come submit_button indipendentemente dal fatto che la traduzione dica "OK" o "Salva modifiche". In modo simile, il pulsante che chiude una finestra di dialogo o di messaggio è sempre un dismiss_button, anche se in realtà contiene "OK" o "Annulla".

La radice può anche essere ** omessa ** in alcuni casi, di solito quando il suffisso da solo è sufficiente per identificare la traduzione. Ad esempio, è improbabile che una pagina o una finestra di dialogo abbia più di un titolo e il contenuto del titolo è già indicato nello spazio dei nomi di terzo livello! Quindi il suffisso può stare da solo.

I suffissi sono anche sufficienti per identificare l'oggetto e i componenti del corpo di un messaggio di posta elettronica poiché ogni messaggio di posta elettronica avrà solo una riga dell'oggetto e un corpo. Nota che il trattino basso iniziale viene omesso in questi casi: userai solo title, subject, o body come chiave ID.

# Riutilizzo delle traduzioni

Gli esclusivi riferimenti chiave di Flarum svolgono lo stesso ruolo delle ancore YAML, ma sono migliori sotto un aspetto:puoi anche fare riferimento alle chiavi in un file diverso! Per questo motivo, è necessario utilizzare la ** chiave di traduzione completa ** quando si fa riferimento. Ecco un esempio più realistico di come funzionano i riferimenti, completo di spaziatura dei nomi:

core:

  forum:
    header:
      log_in_link: => core.ref.log_in

    log_in:
      submit_button: => core.ref.log_in
      title: => core.ref.log_in

  ref:
    log_in: Log In

Come puoi vedere, vogliamo riutilizzare un'unica traduzione in tre contesti diversi (incluse due posizioni): (1) come collegamento visualizzato nell'intestazione del sito, (2) come un pulsante visualizzato nella modalità di login, e (3) come il titolo di quel modale. Quindi tutte e tre queste chiavi sono state impostate per fare riferimento alla stessa chiave di traduzione completa.

La traduzione riutilizzata è identificata da una chiave che omette il suffisso, come specificato più su, e si trova in ref. Quest'ultima misura è necessaria per evitare conflitti che possono verificarsi se a una traduzione riutilizzata viene assegnato lo stesso nome di una chiave di spaziatura dei nomi di secondo livello. (emailè un esempio lampante.)

ref semplifica anche il monitoraggio del riutilizzo della traduzione. Immagina cosa succederebbe se imposti gli scalari per il pulsante e il titolo a cui fare riferimento core.forum.header.log_in_link:

core:

  forum:
    header:
      log_in_link: => Log In

    log_in:
      submit_button: => core.forum.header.log_in_link  # Non fare mai riferimento alle chiavi
      title: => core.forum.header.log_in_link          # che non sono in "ref"!

Sarebbe molto facile cambiare la traduzione per il collegamento dell'intestazione senza rendersi conto che stai cambiando anche le cose nel modale di accesso, per non parlare delle estensioni che potrebbero anche fare riferimento a quella chiave! Questo genere di cose sarà meno probabile che si verifichi se mantieni le traduzioni riutilizzate in ref.

Per questo motivo, qualsiasi riferimento chiave nelle risorse principali (opens new window) ** deve ** puntare alle chiavi in core.ref. I riferimenti chiave nelle risorse per le estensioni in bundle possono puntare a una delle due posizioni:

  • Le traduzioni specifiche dell'estensione dovrebbero andare in ref dei file locali dell'estensione.

  • Le traduzioni utilizzate sia dall'estensione che dal core dovrebbero essere inserite in core.ref.

Le estensioni di terze parti sono invitate a fare riferimento alle chiavi in core.ref, ma tieni presente che non possiamo aggiungere traduzioni in base al per estensioni di terze parti. Uno sviluppatore di terze parti che desidera riutilizzare una traduzione diversa da core.ref sarà necessario aggiungere una traduzione duplicata con chiave appropriata al file delle impostazioni locali dell'estensione.

Nessuna estensione dovrebbe mai fare riferimento a una chiave da un'altra estensione, poiché ciò comporterà una dipendenza.

Un'ultima avvertenza: le chiavi di traduzione in ref non dovrebbero ** mai ** essere inserite direttamente nel codice. Questo perché i localizzatori potrebbero finire per creare una traduzione per sostituire ogni riferimento a una chiave di traduzione riutilizzata, nel qual caso avrebbero il diritto di rimuovere quella chiave dal file locale. Se una tale chiave venisse utilizzata nel codice, finirebbe senza una risorsa corrispondente per tradurla!

# Aggiunta di commenti

I commenti (e le righe vuote) dovrebbero essere aggiunti ai file delle impostazioni locali in modo che i localizzatori trovino più facile la navigazione all'interno del codice.

Abbiamo incluso alcuni ** blocchi dei commenti ** nel modello di file locale incluso con lo scheletro dell'estensione. Sono lì per ricordare agli sviluppatori alcuni concetti di base: le chiavi di traduzione non dovrebbero essere usate in più di un posto; le chiavi per le traduzioni riutilizzate non devono mai essere inserite direttamente nel codice; e così via.

È necessario aggiungere ** righe di commento ** su ogni chiave di secondo o terzo livello, per fornire ai localizzatori una descrizione più completa della posizione coperta da tale chiave. Quando si copiano chiavi esistenti, assicurarsi di copiare anche il commento (e modificarlo se necessario). Se aggiungi una nuova chiave di terzo livello, ricordati evidenziarla con un commento per spiegare la posizione da aggiungere.

Potresti anche voler aggiungere ** commenti in linea ** dopo una traduzione specifica per fornire ai localizzatori ulteriori informazioni su quella traduzione (come il fatto che una traduzione può essere pluralizzata se necessario).

# Appendice B: Codifica per il mondo

In questa appendice, vorremmo offrire alcuni suggerimenti che possono aiutarti a evitare alcune delle trappole più comuni nel processo di internazionalizzazione. Estrarre il linguaggio dal codice è uno dei compiti più banali che un programmatore deve affrontare, ma se non presti la dovuta attenzione alle sottigliezze, è probabile che finirai con il provocare ai tuoi localizzatori uno o due mal di testa inutili.

Naturalmente, non si tratta solo di rendere la vita più facile ai localizzatori. Perché quando hanno mal di testa, verranno da te per chiedere aiuto, spesso mesi (o addirittura anni) dopo che ti sei lasciato alle spalle il progetto e sei passato a qualcos'altro! È il tipo di situazione in cui un grammo o due di prevenzione possono davvero valere diversi mal di testa in meno per tutti i soggetti coinvolti.

Probabilmente è impossibile evitare completamente i problemi di localizzazione; ci sono semplicemente troppe variabili. Ma seguendo alcune semplici linee guida, dovresti essere in grado di evitare molti problemi prima che si verifichino.

# Elimina tutto il testo codificato!

Questo probabilmente è ovvio. Dopotutto, se hai intenzione di prenderti la briga di estrarre le traduzioni, potresti anche voler finire il lavoro, giusto? Ebbene sì, ma è più facile a dirsi che a farsi. È davvero abbastanza insolito trovare un programma che non abbia almeno alcuni bit di testo codificato che fluttuano da qualche parte.

Anche piccoli frammenti di testo possono causare problemi ai localizzatori.Una virgola qui, due punti là, pforse un paio di parentesi inserite per rendere la pagina più leggibile: cose del genere possono causare problemi ai localizzatori. Dopo tutto, non tutte le lingue usano gli stessi glifi per queste cose! Anche uno spazio codificato può essere un problema per qualcuno che cerca di tradurre l'interfaccia in una lingua che non utilizza spazi per separare le parole.

In generale, qualsiasi testo visualizzato che non è fornito da una variabile o il risultato di un calcolo * deve * essere incluso nei file delle impostazioni locali. È facile a dirsi, ma in realtà per farlo ci vuole un po' di perseveranza.

# Evita sintassi codificata

Il testo codificato non è l'unico modo in cui il codice può creare problemi ai localizzatori. Problemi di sintassi codificata si verificano quando il codice forza le parole in un ordine specifico che non funzionerà in altre lingue. Generalmente sono il risultato dell'utilizzo di due traduzioni dove solo una sarebbe più appropriata.

Per un esempio, diamo un'occhiata alla riga di testo stampata vicino alla parte inferiore del Modale di login (opens new window):

Non hai un account? Registrati

Inizialmente abbiamo codificato questa riga come due traduzioni, separate da uno spazio codificato.

before_sign_up_link: "Non hai un account?"
sign_up: Registrati

C'erano buone ragioni per farlo in questo modo. Per prima cosa, ha reso facile trasformare la seconda metà in un collegamento. E poiché la seconda traduzione viene riutilizzata altrove, tenerla separata sembrava un gioco da ragazzi.

Ma c'erano problemi con questo approccio. Lo spazio codificato sembrava suscitare problemi per alcuni localizzatori, come menzionato sopra. E dividere questo testo in due stringhe renderebbe impossibile il rendering della riga come una singola frase con il collegamento incorporato nel mezzo:

Se non hai ancora un account, puoi [registrarti] (#)!

Poiché sembrava possibile che un localizzatore avesse bisogno di questo tipo di flessibilità, abbiamo optato per astrarre la riga come una singola traduzione, utilizzando tag in stile HTML per racchiudere il testo del collegamento:

sign_up_text: "Non hai un account? <a>Registrati</a>"

Questo inserisce lo spazio (precedentemente codificato) nella traduzione, quindi i localizzatori che non ne hanno bisogno possono rimuoverlo. E i tag possono essere posizionati liberamente all'interno della traduzione, rendendo questo approccio molto più flessibile.

La morale di questa storia è: quando hai due porzioni di testo adiacenti che sembrano correlate l'una all'altra grammaticamente, o anche semanticamente, dovresti pensare a trovare un modo per incorporarle entrambe in un'unica traduzione. I tuoi localizzatori potrebbero avere motivo di ringraziarti!

Potremmo anche concludere che la presenza di piccole parti di testo codificato, come lo spazio codificato in questo esempio, potrebbe essere una sorta di odore di codice (opens new window) che indica la presenza di un problema più profondo. Non è sempre così, ma è una possibilità che vale la pena di prendere in considerazione.

# Tieni gli occhi aperti sui plurali!

Sono sorprendentemente facili da trascurare. Naturalmente, la necessità di supporto alla pluralizzazione è abbastanza ovvia qui:

A Toby piace questo. A te piace questo. A Toby e Franz piace questo.

E la situazione è complicata dalla presenza del pronome in seconda persona, dato che in inglese assume sempre la forma plurale, anche quando si parla di una persona. Ecco perchè chiamare app.translator è così complicato nel codice che restituisce le frasi precedenti per l'estensione Mi piace (opens new window).

Ora guarda questo insieme di frasi simile, prodotto da codice simile nell'estensione Citazioni (opens new window):

Toby ha risposto a questo. Hai risposto a questo. Toby e Franz hanno risposto a questo.

In inglese, il passato semplice non è influenzato dalla pluralizzazione. Poiché la frase verbale è sempre la stessa, sarebbe abbastanza facile ignorare i plurali e usare il metodo app.translator.trans() per produrre l'unica traduzione necessaria. Ovviamente, non funzionerebbe per il localizzatore francese, che ha bisogno di declinare il verbo in modo diverso in ciascuna delle tre frasi precedenti.

Questo è il tipo di situazione in cui il lavoro monotono dell'astrazione linguistica richiede un po 'di cura e attenzione in più. Ricordati di chiederti se ogni nome (o pronome) può essere plurale. Se è possibile, assicurati di utilizzare l'estensione app.translator.transChoice()e passare una variabile appropriata al traduttore. Ovviamente non è necessario fornire traduzioni varianti nelle risorse in inglese.

mentioned_by_text: "{users} replied to this."       # Può essere pluralizzato ...
mentioned_by_self_text: "{users} replied to this."  # Può essere pluralizzato ...

BMa sarebbe un'ottima idea aggiungere un commento dopo le traduzioni in questione, per avvisare i localizzatori del fatto che il codice supporterà l'aggiunta di tali varianti, qualora fossero necessarie.

# Riutilizza le traduzioni, non le chiavi!

Se le chiavi di spaziatura dei nomi si combinano per formare una specifica completa di dove viene utilizzata una traduzione, e la chiave ID specifica esattamente come viene utilizzata la traduzione e cosa dice, è ovvio che ogni chiave di traduzione completa deve essere unica. In altre parole: * non dovresti mai usare la stessa chiave più di una volta! *

Sebbene questo possa sembrare inefficiente, c'è una buona ragione per fare le cose in questo modo: è il modo più semplice per garantire che i localizzatori abbiano la flessibilità di cui hanno bisogno. Se riutilizzi le chiavi nel codice, alla fine incontrerai un intoppo. I tuoi localizzatori non saranno in grado di trovare una singola espressione che si adatti a ogni contesto in cui hai usato una chiave o altro, e poi inizieranno a infastidirti per correggere il tuo codice.

Fortunatamente, puoi evitare molti di questi problemi se ti occupi semplicemente delle traduzioni dei nomicorrettamente, assegna un nome alle tue chiavi ID, e riutilizza le traduzioni invece delle chiavi. Sebbene possa sembrare un fastidio, a lungo termine, il formato standard renderà la localizzazione molto più semplice per * tutti *.