7.5 KiB
| sidebar_position | title |
|---|---|
| 3 | Translate the site using resources |
Location files
In order to be able to use localization, we will use resource files.
Create the Resources directory at the root of the site.
In this directory must be the resource files corresponding to your pages, the naming pattern is the directory of the page, a point, the name of the page then the language.
Example :
MyBeautifulAdmin
│
└───Resources
│ │ Pages.List.fr-FR.resx
│ │ Pages.List.resx
│ │ ...
│
└───Pages
│ │ List.razor
│ │ ...
Creation of localization files
In the Resources directory, right click Add => New Item..., in the list select Resources File.
The file name will be Pages.List.resx, the file with no language will be the default if the language is not found.
Add your first translation, resource file works in key/value:
| Name | Value |
|---|---|
| Title | Items List |
Create the file for the French language Pages.List.fr-FR.resx
| Name | Value |
|---|---|
| Title | Liste des éléments |
Here is an example rendering of one of the resource files:
Using Localization Files
Open the class Pages/List.razor.cs and add the service allowing to use the localization.
public partial class List
{
[Inject]
public IStringLocalizer<List> Localizer { get; set; }
...
Open the Pages/List.razor page and use the Localizer to call up the resources:
@page "/list"
@using MyBeautifulAdmin.Models
<h3>@Localizer["Title"]</h3>
...
Concept: Resource files
You can include resources, such as strings, images, or object data, in resources files to make them easily available to your application. The .NET Framework offers five ways to create resources files:
- Create a text file that contains string resources. You can use Resource File Generator (resgen.exe) to convert the text file into a binary resource (.resources) file. You can then embed the binary resource file in an application executable or an application library by using a language compiler, or you can embed it in a satellite assembly by using Assembly Linker (Al.exe).
- Create an XML resource (.resx) file that contains string, image, or object data. You can use Resource File Generator (resgen.exe) to convert the .resx file into a binary resource (.resources) file. You can then embed the binary resource file in an application executable or an application library by using a language compiler, or you can embed it in a satellite assembly by using Assembly Linker (Al.exe).
- Create an XML resource (.resx) file programmatically by using types in the System.Resources namespace. You can create a .resx file, enumerate its resources, and retrieve specific resources by name.
- Create a binary resource (.resources) file programmatically. You can then embed the file in an application executable or an application library by using a language compiler, or you can embed it in a satellite assembly by using Assembly Linker (Al.exe).
- Use Visual Studio to create a resource file and include it in your project. Visual Studio provides a resource editor that lets you add, delete, and modify resources. At compile time, the resource file is automatically converted to a binary .resources file and embedded in an application assembly or satellite assembly.
:::danger Do not use resource files to store passwords, security-sensitive information, or private data. :::
Resources in .resx files
Unlike text files, which can only store string resources, XML resource (.resx) files can store strings, binary data such as images, icons, and audio clips, and programmatic objects.
A .resx file contains a standard header, which describes the format of the resource entries and specifies the versioning information for the XML that is used to parse the data.
The resource file data follows the XML header.
Each data item consists of a name/value pair that is contained in a data tag.
Its name attribute defines the resource name, and the nested value tag contains the resource value.
For string data, the value tag contains the string.
For example, the following data tag defines a string resource named prompt whose value is "Enter your name:".
<data name="prompt" xml:space="preserve">
<value>Enter your name:</value>
</data>
The following example shows a portion of a .resx file that includes an Int32 resource and a bitmap image.
<data name="i1" type="System.Int32, mscorlib">
<value>20</value>
</data>
<data name="flag" type="System.Drawing.Bitmap, System.Drawing,
Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
mimetype="application/x-microsoft.net.object.bytearray.base64">
<value>
AAEAAAD/////AQAAAAAAAAAMAgAAADtTeX…
</value>
</data>
:::caution Because .resx files must consist of well-formed XML in a predefined format, we do not recommend working with .resx files manually, particularly when the .resx files contain resources other than strings. Instead, Visual Studio provides a transparent interface for creating and manipulating .resx files. :::
Concept: Culture
Culture names and identifiers
The CultureInfo class specifies a unique name for each culture, based on RFC 4646.
The name is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code associated with a country or region.
In addition, for apps that target .NET Framework 4 or later and are running under Windows 10 or later, culture names that correspond to valid BCP-47 language tags are supported.
The format for the culture name based on RFC 4646 is languagecode2-country/regioncode2, where languagecode2 is the two-letter language code and country/regioncode2 is the two-letter subculture code.
Examples include ja-JP for Japanese (Japan) and en-US for English (United States).
In cases where a two-letter language code is not available, a three-letter code derived from ISO 639-2 is used.
Some culture names also specify an ISO 15924 script.
For example, Cyrl specifies the Cyrillic script and Latn specifies the Latin script.
A culture name that includes a script uses the pattern languagecode2-scripttag-country/regioncode2.
An example of this type of culture name is uz-Cyrl-UZ for Uzbek (Cyrillic, Uzbekistan).
On Windows operating systems before Windows Vista, a culture name that includes a script uses the pattern languagecode2-country/regioncode2-scripttag, for example, uz-UZ-Cyrl for Uzbek (Cyrillic, Uzbekistan).
A neutral culture is specified by only the two-letter, lowercase language code.
For example, fr specifies the neutral culture for French, and de specifies the neutral culture for German.
:::info
There are two culture names that contradict this rule. The cultures Chinese (Simplified), named zh-Hans, and Chinese (Traditional), named zh-Hant, are neutral cultures.
The culture names represent the current standard and should be used unless you have a reason for using the older names zh-CHS and zh-CHT.
:::
The current culture and current UI culture
Every thread in a .NET application has a current culture and a current UI culture. The current culture determines the formatting conventions for dates, times, numbers, and currency values, the sort order of text, casing conventions, and the ways in which strings are compared. The current UI culture is used to retrieve culture-specific resources at run time.