You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
161 lines
7.5 KiB
161 lines
7.5 KiB
---
|
|
sidebar_position: 3
|
|
title: 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.
|
|
|
|
```csharp title="Pages/List.razor.cs"
|
|
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:
|
|
|
|
```cshtml title="Pages/List.razor"
|
|
@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:"`.
|
|
|
|
```xml
|
|
<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.
|
|
|
|
```xml
|
|
<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.
|
|
|