Condividi tramite

Localizzazione

  • Articolo

Browse sample. Esplorare l'esempio

La localizzazione è il processo di adattamento di un'app per soddisfare i requisiti linguistici o culturali specifici di un mercato di destinazione. Per localizzare un'app, potrebbe essere necessario tradurre il testo e le immagini in più lingue. Un'app localizzata visualizza automaticamente il testo tradotto in base alle impostazioni cultura del dispositivo.

.NET include un meccanismo per la localizzazione delle app usando i file di risorse. Un file di risorse archivia testo e altro contenuto come coppie nome/valore che consentono all'app di recuperare il contenuto per una chiave fornita. I file di risorse consentono di separare il contenuto localizzato dal codice dell'app. Oltre a archiviare testo, i file di risorse possono anche archiviare immagini e dati binari. Tuttavia, i dispositivi hanno una gamma di dimensioni e densità dello schermo e ogni piattaforma ha funzionalità per la visualizzazione di immagini dipendenti dalla densità. Pertanto, la funzionalità della piattaforma deve essere usata per localizzare le immagini invece di archiviarle nei file di risorse.

Per localizzare un'app .NET Multipiattaforma App UI (.NET MAUI), è necessario:

  1. Creare file di risorse per archiviare le stringhe. Per altre informazioni, vedere Creare file di risorse per archiviare stringhe.
  2. Specificare la lingua neutra dell'app. Per altre informazioni, vedere Specificare la lingua neutra dell'app.
  3. Eseguire la configurazione della piattaforma. Per altre informazioni, vedere Eseguire la configurazione della piattaforma.
  4. Localizzare il testo. Per altre informazioni, vedere Localizzare il testo.
  5. Localizzare le immagini. Per altre informazioni, vedere Localizzare le immagini.
  6. Localizzare il nome dell'app. Per altre informazioni, vedere Localizzare il nome dell'app.
  7. Testare la localizzazione. Per altre informazioni, vedere Testare la localizzazione.

Inoltre, è possibile specificare la direzione del layout di un'app. Per altre informazioni, vedere Localizzazione da destra a sinistra.

Creare file di risorse per archiviare stringhe

I file di risorse .NET sono file XML con estensione resx compilati in file di risorse binarie (con estensione resources) durante il processo di compilazione. Un'app localizzata contiene in genere un file di risorse predefinito con tutte le stringhe usate nell'app e i file di risorse per ogni lingua supportata.

I file di risorse contengono le informazioni seguenti per ogni elemento:

  • Name specifica la chiave utilizzata per accedere al testo nel codice.
  • Value specifica il testo tradotto.
  • Il commento è un campo facoltativo contenente informazioni aggiuntive.

È possibile aggiungere un file di risorse con la finestra di dialogo Aggiungi nuovo elemento in Visual Studio:

Screenshot of adding a resource file in Visual Studio.

Dopo aver aggiunto il file, è possibile aggiungere righe per ogni risorsa di testo:

Screenshot of the default strings for the app.

L'elenco a discesa Access Modifier determina il modo in cui Visual Studio genera la classe usata per accedere alle risorse. Se si imposta il modificatore di accesso su Pubblico o Interno , viene generata una classe con il livello di accessibilità specificato. L'impostazione del modificatore di accesso su Nessuna generazione di codice non genera un file di classe. Il file di risorse predefinito deve essere configurato per generare un file di classe, che restituisce un file con . Estensione Designer.cs aggiunta al progetto.

Dopo aver creato il file di risorse predefinito, è possibile creare file aggiuntivi per ogni impostazione locale supportata dall'app. Ogni file di risorse aggiuntivo deve avere lo stesso nome file radice del file di risorse predefinito, ma deve includere anche la lingua e le impostazioni cultura facoltative nel nome file. Ad esempio, se si aggiunge un file di risorse denominato AppResources.resx, è anche possibile creare file di risorse denominati AppResources.en-US.resx e AppResources.fr-FR.resx per contenere le risorse localizzate rispettivamente per le impostazioni cultura inglese (Stati Uniti) e francese (Francia). È inoltre necessario impostare il modificatore di accesso per ogni file di risorse aggiuntivo su Nessuna generazione di codice.

In fase di esecuzione, l'app tenta di risolvere una richiesta di risorsa in ordine di specificità. Ad esempio, se le impostazioni cultura del dispositivo sono en-US , l'applicazione cerca i file di risorse in questo ordine:

  1. AppResources.en-US.resx
  2. AppResources.en.resx
  3. AppResources.resx (impostazione predefinita)

Lo screenshot seguente mostra un file di traduzione spagnolo denominato AppResources.es.resx:

Screenshot of the Spanish strings for the app.

Il file di risorse localizzato usa gli stessi valori Name specificati nel file predefinito, ma contiene stringhe di lingua spagnola nella colonna Valore . Inoltre, il modificatore di accesso è impostato su Nessuna generazione di codice.

Specificare la lingua neutra dell'app

Affinché i file di risorse .NET funzionino correttamente, l'app deve avere una lingua neutra specificata. Questa è la lingua le cui risorse vengono usate se non è possibile trovare risorse per le impostazioni locali. Per specificare la lingua neutra:

  1. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto di app .NET MAUI e scegliere Proprietà.

  2. Selezionare la pagina delle proprietà Generale> pacchetto e selezionare la lingua e le impostazioni cultura appropriate nell'elenco a discesa Lingua indipendente assembly:

    Screenshot of setting the neutral language for the assembly.

  3. Salvare le modifiche.

In alternativa, aggiungere l'elemento <NeutralLanguage> al primo <PropertyGroup> nel file di progetto e specificare le impostazioni locali scelte come valore:

<NeutralLanguage>en-US</NeutralLanguage>

Avviso

Se non si specifica una lingua neutra, la ResourceManager classe restituisce null i valori per qualsiasi lingua senza un file di risorse. Quando si specifica una lingua neutra, la ResourceManager classe restituisce i risultati dal file di risorse della lingua neutra per le lingue non supportate. Pertanto, è consigliabile specificare sempre una lingua neutra in modo che il testo venga visualizzato per le lingue non supportate.

Eseguire la configurazione della piattaforma

È necessaria un'installazione aggiuntiva in iOS, Mac Catalyst e Windows, in modo che tutti i controlli MAUI .NET siano localizzati.

iOS e Mac Catalyst

In iOS e Mac Catalyst è necessario dichiarare tutte le lingue supportate nel file Info.plist della piattaforma nel progetto di app MAUI .NET. A tale scopo, aprire il file Info.plist per la piattaforma scelta in un editor XML e creare una matrice per la CFBundleLocalizations chiave. Specificare quindi i valori di matrice che corrispondono ai file di risorse. Assicurarsi inoltre di impostare una lingua prevista tramite la CFBundleDevelopmentRegion chiave :

<key>CFBundleLocalizations</key>
<array>
    <string>de</string>
    <string>es</string>
    <string>fr</string>
    <string>ja</string>
    <string>pt</string> <!-- Brazil -->
    <string>pt-PT</string> <!-- Portugal -->
    <string>ru</string>
    <string>zh-Hans</string>
    <string>zh-Hant</string>
</array>
<key>CFBundleDevelopmentRegion</key>
<string>en</string>

In alternativa, in Esplora soluzioni in Visual Studio aprire il file Info.plist per la piattaforma scelta nell'editor PList generico. Creare quindi una matrice per la CFBundleLocalizations chiave e fornire valori di matrice che corrispondono ai file di risorse. Assicurarsi inoltre di impostare una lingua prevista tramite la CFBundleDevelopmentRegion chiave :

Screenshot of the supported locales for the app in the generic Info.plist editor.

Per altre informazioni sul file Info.plist , vedere Elenco delle proprietà delle informazioni.

Windows

Per supportare più lingue in un'app MAUI .NET in Windows, è necessario dichiarare ogni lingua supportata nel file Platforms\Windows\Package.appxmanifest del progetto di app MAUI .NET:

  1. Aprire il file Package.appxmanifest in un editor di testo e individuare la sezione seguente:

    <Resources>
    <Resource Language="x-generate"/>
</Resources>

  2. Sostituire <Resource Language="x-generate"> con <Resource /> gli elementi per ognuna delle lingue supportate:

    <Resources>
    <Resource Language="en-US"/>
    <Resource Language="de-DE"/>
    <Resource Language="es-ES"/>
    <Resource Language="fr-FR"/>
    <Resource Language="ja-JP"/>
    <Resource Language="pt-BR"/>
    <Resource Language="pt-PT"/>
    <Resource Language="ru-RU"/>
    <Resource Language="zh-CN"/>
    <Resource Language="zh-TW"/>
</Resources>

  3. Salvare le modifiche.

Localizzare il testo

Il testo viene localizzato usando una classe generata dal file di risorse predefinito. La classe viene denominata in base al nome file di risorsa predefinito. Dato un nome file di risorsa predefinito di AppResources.resx, Visual Studio genera una classe corrispondente denominata AppResources contenente proprietà statiche per ogni voce nel file di risorse.

In XAML, il testo localizzato può essere recuperato usando l'estensione x:Static di markup per accedere alle proprietà statiche generate:

<ContentPage ...
             xmlns:strings="clr-namespace:LocalizationDemo.Resources.Strings">
    <VerticalStackLayout>
        <Label Text="{x:Static strings:AppResources.NotesLabel}" />
        <Entry Placeholder="{x:Static strings:AppResources.NotesPlaceholder}" />
        <Button Text="{x:Static strings:AppResources.AddButton}" />
    </VerticalStackLayout>
</ContentPage>

Per altre informazioni sull'estensione x:Static di markup, vedere estensione di markup x:Static.

Il testo localizzato può essere recuperato anche nel codice:

Label notesLabel = new Label();
notesLabel.Text = AppResources.NotesLabel,

Entry notesEntry = new Entry();
notesEntry.Placeholder = AppResources.NotesPlaceholder,

Button addButton = new Button();
addButton.Text = AppResources.AddButton,

Le proprietà nella AppResources classe usano il valore della proprietà per determinare il CurrentUICulture file di risorse da cui recuperare i valori.

Localizzare le immagini

Oltre a archiviare testo, i file di risorse possono anche archiviare immagini e dati binari. Tuttavia, i dispositivi hanno una gamma di dimensioni e densità dello schermo e ogni piattaforma ha funzionalità per la visualizzazione di immagini dipendenti dalla densità. Pertanto, la funzionalità della piattaforma deve essere usata per localizzare le immagini invece di archiviarle nei file di risorse.

Android

In Android le immagini localizzate, note come drawable, vengono archiviate usando una convenzione di denominazione basata su cartelle nella cartella Platforms\Android\Resources . Le cartelle devono essere denominate disegnabili con un suffisso per la lingua e le impostazioni cultura. Ad esempio, la cartella in lingua spagnola è denominata drawable-es. Il nome della cartella drawable deve contenere le immagini per la lingua e le impostazioni cultura predefinite. L'azione di compilazione di ogni immagine deve essere impostata su AndroidResource.

Nota

Anziché impostare singoli file sull'azione di compilazione AndroidResource , il contenuto di una cartella specifica può essere impostato su questa azione di compilazione aggiungendo il codice XML seguente al file di progetto (con estensione csproj) dell'app:

<ItemGroup Condition="$(TargetFramework.Contains('-android'))">
  <AndroidResource Include="Platforms\Android\Resources\**" TargetPath="%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>

Questo esempio imposta qualsiasi contenuto nella cartella Platforms\Android\Resources , incluso il contenuto nelle sottocartelle, sull'azione di compilazione AndroidResource . Imposta anche il percorso di output per ogni file con questa azione di compilazione.

Nel nome della cartella sono necessari solo due caratteri quando si specifica una lingua di primo livello, ad esempio es. Tuttavia, quando si specificano impostazioni locali complete, il formato del nome della cartella richiede un trattino e un r minuscolo per separare la lingua dalle impostazioni cultura. Ad esempio, la cartella delle impostazioni locali del Messico (es-MX) deve essere denominata drawable-es-rMX. I nomi dei file di immagine in ogni cartella delle impostazioni locali devono essere identici:

Screenshot of the localized folder structure in Visual Studio for images on Android.

iOS

In iOS le immagini localizzate vengono archiviate usando una convenzione di denominazione basata su cartelle nella cartella Platforms\iOS\Resources . Le cartelle devono essere denominate con la lingua e le impostazioni cultura facoltative, seguite da .lproj. Ad esempio, la cartella in lingua spagnola è denominata es.lproj. L'azione di compilazione di ogni immagine deve essere impostata su BundleResource.

Nota

Anziché impostare singoli file sull'azione di compilazione BundleResource , il contenuto di una cartella specifica può essere impostato su questa azione di compilazione aggiungendo il codice XML seguente al file di progetto (con estensione csproj) dell'app:

<ItemGroup Condition="$(TargetFramework.Contains('-ios'))">
  <BundleResource Include="Platforms\iOS\Resources\**" TargetPath="%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>

Questo esempio imposta qualsiasi contenuto nella cartella Platforms\iOS\Resources , incluso il contenuto nelle sottocartelle, sull'azione di compilazione BundleResource . Imposta anche il percorso di output per ogni file con questa azione di compilazione.

Nel nome della cartella sono necessari solo due caratteri quando si specifica una lingua di primo livello, ad esempio es. Tuttavia, quando si specificano impostazioni locali complete, il formato del nome della cartella richiede un trattino per separare la lingua dalle impostazioni cultura. Ad esempio, la cartella delle impostazioni locali del Messico (es-MX) deve essere denominata es-MX.lproj. I nomi dei file di immagine in ogni cartella delle impostazioni locali devono essere identici:

Screenshot of the localized folder structure in Visual Studio for images on iOS.

Inoltre, nel file di progetto è necessario impostare la proprietà di IPhoneResourcePrefix compilazione sulla cartella contenente le cartelle di immagini localizzate:

<PropertyGroup Condition="$(TargetFramework.Contains('-ios'))">
  <IPhoneResourcePrefix>Platforms/iOS/Resources</IPhoneResourcePrefix>
</PropertyGroup>

Se un'immagine non è presente per una determinata lingua, iOS esegue il fallback alla cartella predefinita della lingua nativa e carica l'immagine da questa posizione.

Mac Catalyst

In Mac Catalyst le immagini localizzate vengono archiviate usando una convenzione di denominazione basata su cartelle nella cartella Platforms\MacCatalyst\Resources . Le cartelle devono essere denominate con la lingua e le impostazioni cultura facoltative, seguite da .lproj. Ad esempio, la cartella in lingua spagnola è denominata es.lproj. L'azione di compilazione di ogni immagine deve essere impostata su BundleResource.

Nota

Anziché impostare singoli file sull'azione di compilazione BundleResource , il contenuto di una cartella specifica può essere impostato su questa azione di compilazione aggiungendo il codice XML seguente al file di progetto (con estensione csproj) dell'app:

<ItemGroup Condition="$(TargetFramework.Contains('-maccatalyst'))">
  <BundleResource Include="Platforms\MacCatalyst\Resources\**" TargetPath="%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>

Questo esempio imposta qualsiasi contenuto nella cartella Platforms\MacCatalyst\Resources , incluso il contenuto nelle sottocartelle, sull'azione di compilazione BundleResource . Imposta anche il percorso di output per ogni file con questa azione di compilazione.

Nel nome della cartella sono necessari solo due caratteri quando si specifica una lingua di primo livello, ad esempio es. Tuttavia, quando si specificano impostazioni locali complete, il formato del nome della cartella richiede un trattino per separare la lingua dalle impostazioni cultura. Ad esempio, la cartella delle impostazioni locali del Messico (es-MX) deve essere denominata es-MX.lproj. I nomi dei file di immagine in ogni cartella delle impostazioni locali devono essere identici:

Screenshot of the localized folder structure in Visual Studio for images on MacCatalyst.

Inoltre, nel file di progetto è necessario impostare la proprietà di IPhoneResourcePrefix compilazione sulla cartella contenente le cartelle di immagini localizzate:

<PropertyGroup Condition="$(TargetFramework.Contains('-maccatalyst'))">
  <IPhoneResourcePrefix>Platforms/MacCatalyst/Resources</IPhoneResourcePrefix>
</PropertyGroup>

Se un'immagine non è presente per una determinata lingua, Mac Catalyst esegue il fallback alla cartella predefinita della lingua nativa e carica l'immagine da questa posizione.

Windows

In Windows le immagini localizzate vengono archiviate usando una convenzione di denominazione basata su cartelle nella cartella Platforms\Windows\Assets\Images . Le cartelle devono essere denominate con la lingua e le impostazioni cultura facoltative. Ad esempio, la cartella in lingua spagnola è denominata es e la cartella delle impostazioni locali del Messico deve essere denominata es-MX. L'azione di compilazione di ogni immagine deve essere impostata su Contenuto.

Nota

Anziché impostare singoli file sull'azione Compilazione contenuto, il contenuto di una cartella specifica può essere impostato su questa azione di compilazione aggiungendo il codice XML seguente al file di progetto (con estensione csproj) dell'app:

<ItemGroup Condition="$(TargetFramework.Contains('-windows'))">
  <Content Include="Platforms\Windows\Assets\Images\**" TargetPath="%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>

Questo esempio imposta qualsiasi contenuto nella cartella Platforms\Windows\Assets\Images , incluso il contenuto nelle sottocartelle, sull'azione Di compilazione contenuto . Imposta anche il percorso di output per ogni file con questa azione di compilazione.

Nel nome della cartella sono necessari solo due caratteri quando si specifica una lingua di primo livello, ad esempio es. Tuttavia, quando si specificano impostazioni locali complete, il formato del nome della cartella richiede un trattino per separare la lingua dalle impostazioni cultura. Ad esempio, la cartella delle impostazioni locali del Messico (es-MX) deve essere denominata es-MX. I nomi dei file di immagine in ogni cartella delle impostazioni locali devono essere identici:

Screenshot of the localized folder structure in Visual Studio for images on Windows.

Utilizzare immagini localizzate

In Android, iOS, Mac Catalyst e Windows le immagini localizzate possono essere utilizzate impostando la Source proprietà di un Image oggetto sul nome file dell'immagine:

<Image Source="flag.png" />

Tuttavia, affinché funzioni in Windows, è necessario modificare il file di progetto dell'app se è stato aggiunto un <Content /> elemento MSBuild per ogni immagine localizzata. A tale scopo, è possibile modificare il file con estensione csproj per rimuovere l'elemento <Content /> MSBuild per ogni immagine. Aggiungere quindi l'elemento MSBuild seguente:

<ItemGroup Condition="$(TargetFramework.Contains('-windows'))">
  <Content Include="Platforms\Windows\Assets\Images\**" TargetPath="%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>

In questo modo tutte le immagini nelle sottocartelle della cartella Platforms\Windows\Assets\Images vengono copiate nella radice del pacchetto dell'app.

Localizzare il nome dell'app

La funzionalità della piattaforma è necessaria per la localizzazione del nome dell'app.

Android

In Android il nome dell'app localizzata può essere archiviato usando una convenzione di denominazione basata su cartelle nella cartella Platforms\Android\Resources . Le cartelle devono essere denominate con un suffisso per la lingua e le impostazioni cultura. Ad esempio, la cartella in lingua spagnola è denominata values-es. Aggiungere un file Strings.xml con un'azione di compilazione AndroidResource a ogni cartella che imposta una stringa sul nome dell'app localizzata.

Nota

Anziché impostare singoli file sull'azione di compilazione AndroidResource , il contenuto di una cartella specifica può essere impostato su questa azione di compilazione aggiungendo il codice XML seguente al file di progetto (con estensione csproj) dell'app:

<ItemGroup Condition="$(TargetFramework.Contains('-android'))">
  <AndroidResource Include="Platforms\Android\Resources\**" TargetPath="%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>

Questo esempio imposta qualsiasi contenuto nella cartella Platforms\Android\Resources , incluso il contenuto nelle sottocartelle, sull'azione di compilazione AndroidResource . Imposta anche il percorso di output per ogni file con questa azione di compilazione.

Nel nome della cartella sono necessari solo due caratteri quando si specifica una lingua di primo livello, ad esempio es. Tuttavia, quando si specificano impostazioni locali complete, il formato del nome della cartella richiede un trattino e un r minuscolo per separare la lingua dalle impostazioni cultura. Ad esempio, la cartella delle impostazioni locali del Messico (es-MX) deve essere denominata values-es-rMX.

Ogni stringa traducibile è un elemento XML con l'ID risorsa specificato come name attributo e la stringa tradotta come valore. È necessario eseguire l'escape della stringa in base alle normali regole XML e deve name essere un ID risorsa Android valido (senza spazi o trattini).

Pertanto, per localizzare il nome dell'app, creare un file Strings.xml e aggiungere un <string> elemento come elemento figlio di un <resources> elemento. Impostare quindi l'attributo name su un ID appropriato con la stringa tradotta come valore:

<resources>
    <!-- French -->
    <string name="app_name">Maison</string>
</resources>

Quindi, per usare il nome dell'app localizzata nell'app, aggiungere la Label proprietà a Activity nella classe dell'app MainActivity e impostarne il valore su @string/id:

[Activity(Label = "@string/app_name", Theme = "@style/Maui.SplashTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize | ConfigChanges.Density)]
public class MainActivity : MauiAppCompatActivity
{
    protected override void OnCreate(Bundle savedInstanceState)
    {
        base.OnCreate(savedInstanceState);
    }
}

iOS

In iOS il nome dell'app localizzata viene archiviato usando una convenzione di denominazione basata su cartelle nella cartella Platforms\iOS\Resources . Le cartelle devono essere denominate con la lingua e le impostazioni cultura facoltative, seguite da .lproj. Ad esempio, la cartella in lingua spagnola è denominata es.lproj. Aggiungere un file InfoPlist.strings con un'azione di compilazione BundleResource a ogni cartella che imposta la chiave e il CFBundleDisplayName valore.

Nota

Anziché impostare singoli file sull'azione di compilazione BundleResource , il contenuto di una cartella specifica può essere impostato su questa azione di compilazione aggiungendo il codice XML seguente al file di progetto (con estensione csproj) dell'app:

<ItemGroup Condition="$(TargetFramework.Contains('-ios'))">
  <BundleResource Include="Platforms\iOS\Resources\**" TargetPath="%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>

Questo esempio imposta qualsiasi contenuto nella cartella Platforms\iOS\Resources , incluso il contenuto nelle sottocartelle, sull'azione di compilazione BundleResource . Imposta anche il percorso di output per ogni file con questa azione di compilazione.

La sintassi per i valori stringa localizzati è:

/* comment */
"key"="localized-value";

È consigliabile eseguire l'escape dei caratteri seguenti nelle stringhe:

  • Citazione di \"
  • \\ Barra rovesciata
  • \n Newline

Pertanto, per localizzare il nome dell'app, creare un file InfoPlist.strings e aggiungere un valore per la CFBundleDisplayName chiave al file:

/* French */
CFBundleDisplayName="Maisons";

Altre chiavi che è possibile usare per localizzare stringhe specifiche dell'app sono:

  • CFBundleName - specifica il nome breve del bundle dell'app, che potrebbe essere visualizzato agli utenti in situazioni come l'assenza di un valore per CFBundleDisplayName.
  • CFBundleShortVersionString : specifica il numero di versione del bundle dell'app.
  • NSHumanReadableCopyright - l'informativa sul copyright per il bundle dell'app.

Inoltre, nel file di progetto è necessario impostare la proprietà di IPhoneResourcePrefix compilazione sulla cartella che contiene le cartelle localizzate:

<PropertyGroup Condition="$(TargetFramework.Contains('-ios'))">
  <IPhoneResourcePrefix>Platforms/iOS/Resources</IPhoneResourcePrefix>
</PropertyGroup>

Mac Catalyst

In Mac Catalyst il nome dell'app localizzata viene archiviato usando una convenzione di denominazione basata su cartelle nella cartella Platforms\MacCatalyst\Resources . Le cartelle devono essere denominate con la lingua e le impostazioni cultura facoltative, seguite da .lproj. Ad esempio, la cartella in lingua spagnola è denominata es.lproj. Aggiungere un file InfoPlist.strings con un'azione di compilazione BundleResource a ogni cartella che imposta la chiave e il CFBundleDisplayName valore.

Nota

Anziché impostare singoli file sull'azione di compilazione BundleResource , il contenuto di una cartella specifica può essere impostato su questa azione di compilazione aggiungendo il codice XML seguente al file di progetto (con estensione csproj) dell'app:

<ItemGroup Condition="$(TargetFramework.Contains('-maccatalyst'))">
  <BundleResource Include="Platforms\MacCatalyst\Resources\**" TargetPath="%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>

Questo esempio imposta qualsiasi contenuto nella cartella Platforms\MacCatalyst\Resources , incluso il contenuto nelle sottocartelle, sull'azione di compilazione BundleResource . Imposta anche il percorso di output per ogni file con questa azione di compilazione.

La sintassi per i valori stringa localizzati è:

/* comment */
"key"="localized-value";

È consigliabile eseguire l'escape dei caratteri seguenti nelle stringhe:

  • Citazione di \"
  • \\ Barra rovesciata
  • \n Newline

Pertanto, per localizzare il nome dell'app, creare un file InfoPlist.strings e aggiungere un valore per la CFBundleDisplayName chiave al file:

/* French */
CFBundleDisplayName="Maisons";

Altre chiavi che è possibile usare per localizzare stringhe specifiche dell'app sono:

  • CFBundleName - specifica il nome breve del bundle dell'app, che potrebbe essere visualizzato agli utenti in situazioni come l'assenza di un valore per CFBundleDisplayName.
  • CFBundleShortVersionString : specifica il numero di versione del bundle dell'app.
  • NSHumanReadableCopyright - l'informativa sul copyright per il bundle dell'app.

Inoltre, nel file di progetto è necessario impostare la proprietà di IPhoneResourcePrefix compilazione sulla cartella che contiene le cartelle localizzate:

<PropertyGroup Condition="$(TargetFramework.Contains('-maccatalyst'))">
  <IPhoneResourcePrefix>Platforms/MacCatalyst/Resources</IPhoneResourcePrefix>
</PropertyGroup>

Windows

In Windows il nome dell'app viene definito nel manifesto del pacchetto dell'app. La localizzazione del nome dell'app richiede prima di tutto di specificare la lingua predefinita per l'app e quindi creare un file di risorse stringa per ogni impostazione locale che si intende supportare. La risorsa stringa che rappresenta il nome dell'app localizzata può quindi essere utilizzata nel manifesto del pacchetto dell'app usando lo ms-resource schema URI.

Per altre informazioni sulla localizzazione delle stringhe nel manifesto del pacchetto dell'app, vedi Localizzare le stringhe nell'interfaccia utente e nel manifesto del pacchetto dell'app.

Specificare la lingua predefinita

Per localizzare un nome di app, l'app di Windows deve prima avere una lingua predefinita specificata. Si tratta della lingua le cui risorse vengono usate se non è possibile trovare risorse localizzate per una lingua specifica. Per specificare la lingua predefinita:

  1. In Esplora soluzioni aprire il file Packageappxmanifest nell'editor del manifesto del pacchetto.

  2. Nell'editor del manifesto del pacchetto, nella scheda Applicazione , impostare il campo Lingua predefinita sulla lingua predefinita scelta:

    Screenshot of setting the default language of a Windows app in the package manifest.

  3. Salvare le modifiche.

È necessario specificare almeno una risorsa stringa per il nome dell'app per la lingua predefinita. Si tratta della risorsa caricata se non è possibile trovare una corrispondenza migliore per la lingua preferita dell'utente o le impostazioni della lingua di visualizzazione.

Creare file di risorse di Windows

In Windows il nome dell'app localizzata deve essere archiviato in un file di risorse di Windows per ogni impostazione locale. Un file di risorse di Windows è un file XML con estensione resw compilato in un formato binario e archiviato in un file con estensione pri . Il file resw per ogni impostazione locale deve essere denominato Resources.resw e archiviato usando una convenzione di denominazione basata su cartelle nella cartella Platforms\Windows\Strings . Le cartelle devono essere denominate con la lingua e le impostazioni cultura facoltative. Ad esempio, la cartella in lingua spagnola è denominata es e la cartella delle impostazioni locali del Messico deve essere denominata es-MX.

Attualmente non è disponibile alcun modello di elemento di Visual Studio per la creazione di un file di risorse di Windows in un'app MAUI .NET. Pertanto, per creare un file di risorse di Windows per ogni impostazione locale:

  1. Nella cartella Platforms\Windows del progetto di app .NET MAUI creare una cartella Strings.

  2. Nella cartella Stringhe creare una cartella per ogni impostazione locale.

  3. Nella cartella per ogni impostazione locale creare un file denominato Resources.resw contenente il codice XML seguente:

    <?xml version="1.0" encoding="utf-8"?>
<root>
  <!--
    Microsoft ResX Schema

    Version 2.0

    The primary goals of this format is to allow a simple XML format
    that is mostly human readable. The generation and parsing of the
    various data types are done through the TypeConverter classes
    associated with the data types.

    Example:

    ... ado.net/XML headers & schema ...
    <resheader name="resmimetype">text/microsoft-resx</resheader>
    <resheader name="version">2.0</resheader>
    <resheader name="reader">System.Resources.ResXResourceReader, System.Windows.Forms, ...</resheader>
    <resheader name="writer">System.Resources.ResXResourceWriter, System.Windows.Forms, ...</resheader>
    <data name="Name1"><value>this is my long string</value><comment>this is a comment</comment></data>
    <data name="Color1" type="System.Drawing.Color, System.Drawing">Blue</data>
    <data name="Bitmap1" mimetype="application/x-microsoft.net.object.binary.base64">
        <value>[base64 mime encoded serialized .NET Framework object]</value>
    </data>
    <data name="Icon1" type="System.Drawing.Icon, System.Drawing" mimetype="application/x-microsoft.net.object.bytearray.base64">
        <value>[base64 mime encoded string representing a byte array form of the .NET Framework object]</value>
        <comment>This is a comment</comment>
    </data>

    There are any number of "resheader" rows that contain simple
    name/value pairs.

    Each data row contains a name, and value. The row also contains a
    type or mimetype. Type corresponds to a .NET class that support
    text/value conversion through the TypeConverter architecture.
    Classes that don't support this are serialized and stored with the
    mimetype set.

    The mimetype is used for serialized objects, and tells the
    ResXResourceReader how to depersist the object. This is currently not
    extensible. For a given mimetype the value must be set accordingly:

    Note - application/x-microsoft.net.object.binary.base64 is the format
    that the ResXResourceWriter will generate, however the reader can
    read any of the formats listed below.

    mimetype: application/x-microsoft.net.object.binary.base64
    value   : The object must be serialized with
            : System.Runtime.Serialization.Formatters.Binary.BinaryFormatter
            : and then encoded with base64 encoding.

    mimetype: application/x-microsoft.net.object.soap.base64
    value   : The object must be serialized with
            : System.Runtime.Serialization.Formatters.Soap.SoapFormatter
            : and then encoded with base64 encoding.

    mimetype: application/x-microsoft.net.object.bytearray.base64
    value   : The object must be serialized into a byte array
            : using a System.ComponentModel.TypeConverter
            : and then encoded with base64 encoding.
    -->
  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
    <xsd:element name="root" msdata:IsDataSet="true">
      <xsd:complexType>
        <xsd:choice maxOccurs="unbounded">
          <xsd:element name="metadata">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" />
              </xsd:sequence>
              <xsd:attribute name="name" use="required" type="xsd:string" />
              <xsd:attribute name="type" type="xsd:string" />
              <xsd:attribute name="mimetype" type="xsd:string" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="assembly">
            <xsd:complexType>
              <xsd:attribute name="alias" type="xsd:string" />
              <xsd:attribute name="name" type="xsd:string" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="data">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
                <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
              <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
              <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="resheader">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" />
            </xsd:complexType>
          </xsd:element>
        </xsd:choice>
      </xsd:complexType>
    </xsd:element>
  </xsd:schema>
  <resheader name="resmimetype">
    <value>text/microsoft-resx</value>
  </resheader>
  <resheader name="version">
    <value>2.0</value>
  </resheader>
  <resheader name="reader">
    <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <resheader name="writer">
    <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
</root>

    Nota

    I file di risorse di Windows usano un'azione di compilazione di PRIResource. Questa azione di compilazione non richiede l'impostazione in ogni file con estensione resw in un'app MAUI .NET, perché viene applicata in modo implicito.

  4. Aprire ogni file Resources.resw e aggiungere una risorsa stringa che rappresenta il nome dell'app:

    Screenshot of the resw file editor in Visual Studio on Windows.

    Nota

    Gli identificatori di risorsa non fanno distinzione tra maiuscole e minuscole e devono essere univoci per ogni file di risorse.

  5. Salvare ogni file di risorse di Windows.

Un esempio della cartella e della struttura di file richiesta è illustrata nello screenshot seguente:

Screenshot of the localized folder structure in Visual Studio for strings on Windows.

Utilizzare il nome dell'app localizzata

La risorsa stringa che rappresenta il nome dell'app localizzata può essere utilizzata usando lo ms-resource schema URI:

  1. In Esplora soluzioni aprire il file Packageappxmanifest nell'editor del manifesto del pacchetto.

  2. Nell'editor del manifesto del pacchetto, nella scheda Applicazione , impostare il campo Nome visualizzato su ms-resource: seguito dal nome della risorsa stringa che identifica il nome dell'app:

    Screenshot of setting the localized app name in the package manifest on Windows.

  3. Salvare le modifiche.

Importante

Se i file con estensione resw vengono archiviati in un assembly diverso per il progetto di app MAUI .NET, è necessario specificare un percorso completo del nome della risorsa. In questo modo viene utilizzato il formato ms-resource:Assembly/ResourceFilename/Resource.

Localizzazione da destra a sinistra

La direzione del flusso, o la direzione del layout, è la direzione in cui gli elementi dell'interfaccia utente della pagina vengono analizzati dall'occhio. Alcuni lingue, come l'arabo e l'ebraico, richiedono che gli elementi dell'interfaccia utente vengano disposti da destra a sinistra. Le app MAUI .NET rispettano automaticamente la direzione del flusso del dispositivo in base alla lingua e all'area selezionata. Per informazioni su come recuperare la direzione del flusso del dispositivo, in base alle impostazioni locali, vedere Ottenere la direzione del layout.

Per eseguire l'override della direzione del flusso di un'app, impostare la Window.FlowDirection proprietà . In alternativa, impostare la VisualElement.FlowDirection proprietà per ogni elemento. Queste proprietà ottengono o impostano la direzione in cui gli elementi dell'interfaccia utente vengono trasmessi all'interno di qualsiasi elemento padre che controlla il layout e devono essere impostati su uno dei FlowDirection valori di enumerazione:

  • LeftToRight
  • RightToLeft
  • MatchParent

L'impostazione della FlowDirection proprietà RightToLeft su su un elemento imposta l'allineamento a destra, l'ordine di lettura da destra a sinistra e il layout del controllo da destra a sinistra per il flusso da destra a sinistra.

Avviso

La modifica della FlowDirection proprietà in fase di esecuzione causa un processo di layout costoso che influisce sulle prestazioni.

Il valore predefinito FlowDirection della proprietà per un elemento è MatchParent. Pertanto, un elemento eredita il valore della proprietà FlowDirection dal relativo elemento padre nella struttura ad albero visuale e qualsiasi elemento può sostituire il valore ereditato dal relativo elemento padre.

Suggerimento

Se è necessario modificare la direzione del flusso, impostare la FlowDirection proprietà in una finestra, una pagina o un layout radice. In questo modo tutti gli elementi contenuti nell'app, nella pagina o nel layout radice rispondono in modo appropriato alla direzione del flusso.

Impostazione della piattaforma

Per abilitare le impostazioni locali da destra a sinistra, è necessario prevedere un'impostazione specifica della piattaforma.

Android

Le app create usando il modello di progetto di app MAUI .NET includono automaticamente il supporto per le impostazioni locali da destra a sinistra. Questo supporto è abilitato dall'attributo android:supportsRtl impostato su true nel <application> nodo nel file AndroidManifest.xml dell'app:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application ... android:supportsRtl="true" />
    ...
</manifest>

La localizzazione da destra a sinistra può quindi essere testata modificando il dispositivo o l'emulatore per usare la lingua da destra a sinistra. In alternativa, se sono state attivate le opzioni di sviluppo nell'app Impostazioni, è possibile abilitare Forzare la direzione del layout RTL in Impostazioni > Opzioni sviluppatore. Per informazioni sulla configurazione delle opzioni per sviluppatori, vedere Configurare le opzioni per sviluppatori nel dispositivo in developer.android.com.

iOS e Mac Catalyst

Le impostazioni locali necessarie per la direzione da destra a sinistra devono essere aggiunte come lingua supportata agli elementi matrice della chiave CFBundleLocalizations in Info.plist. L'esempio seguente mostra l'arabo aggiunto alla matrice della chiave CFBundleLocalizations:

<key>CFBundleLocalizations</key>
<array>
    <string>en</string>
    <string>ar</string>
</array>

È quindi possibile testare la localizzazione da destra a sinistra modificando la lingua e l'area nel dispositivo o il simulatore in impostazioni locali da destra a sinistra specificate in Info.plist.

Windows

Le risorse della lingua necessarie devono essere specificate nel nodo <Resources> del file Package.appxmanifest. Sostituire <Resource Language="x-generate"> con <Resource /> gli elementi per ognuna delle lingue supportate. Ad esempio, il markup seguente specifica che sono disponibili le risorse localizzate "en" e "ar":

<Resources>
    <Resource Language="en" />
    <Resource Language="ar" />
</Resources>

La localizzazione da destra a sinistra può essere testata cambiando la lingua e l'area geografica nel dispositivo e scegliendo le impostazioni locali per la direzione da destra a sinistra appropriate.

Testare la localizzazione

In fase di esecuzione, l'app carica le risorse localizzate appropriate per ogni thread, in base alle impostazioni cultura specificate dalla CurrentUICulture proprietà .

Il test della localizzazione viene eseguito al meglio modificando la lingua del dispositivo nell'app Impostazioni in ogni dispositivo.

Avviso

Anche se è possibile impostare il valore di CurrentUICulture nel codice, il comportamento risultante è incoerente tra le piattaforme, pertanto questo non è consigliato per i test.