From debe86261a7b6eb2a49ad7c7f6cfbcf0d512a000 Mon Sep 17 00:00:00 2001 From: Mariana Dematte Date: Tue, 17 Jan 2023 15:56:11 -0800 Subject: [PATCH 1/4] Added basic localization info for template engine --- docs/core/tools/custom-templates.md | 56 +++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/docs/core/tools/custom-templates.md b/docs/core/tools/custom-templates.md index 5b517523de545..585f79a4bc180 100644 --- a/docs/core/tools/custom-templates.md +++ b/docs/core/tools/custom-templates.md @@ -91,6 +91,62 @@ The *template.json* file looks like the following: The *mytemplate* folder is an installable template package. Once the package is installed, the `shortName` can be used with the `dotnet new` command. For example, `dotnet new adatumconsole` would output the `console.cs` and `readme.txt` files to the current folder. +### Template localization +The .NET templates are localizable. If a template is localized for the language matching the current locale, its elements will appear in the same language as the CLI. Localization is optional when creating new templates. + +The localizable elements on a template are: +- Name +- Author +- Description +- Symbols + - Description + - Display Name + - Descriptions and Diplay name of choices for choice paramemters +- Post actions + - description + - Manual instructions + +Localization files have a JSON format, and just one file per culture should exist. The naming convention is: `templatestrings..json`, where `lang code` corresponds to one of the [CultureInfo](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo.name) options. All localization files should be inside the `.template-config\localize` folder. + +The localization JSON consists of key value pairs: +- The key is the reference to an element of `template.json` to be localized. If the element is a child, use the full path with a `/` delimiter. +- The value is the localization string of the element given by the key. + +For more information about localizing templates, see the [dotnet templating wiki's localization page](https://github.com/dotnet/templating/wiki/Localization). + +#### Example +For example, here's *template.json* file with some localiable fields: +```JSON +{ + "$schema": "http://json.schemastore.org/template", + "author": "Microsoft", + "classifications": "Config", + "name": "EditorConfig file", + "description": "Creates an .editorconfig file for configuring code style preferences.", + "symbols": { + "Empty": { + "type": "parameter", + "datatype": "bool", + "defaultValue": "false", + "displayName": "Empty", + "description": "Creates empty .editorconfig instead of the defaults for .NET." + } + } +} +``` + +And some fields are to be localizes to Brazilian Portuguese. The filename will be `templatestrings.pt-BR.json` to match the culture, and it would look like: + +```JSON +{ + "author": "Microsoft", + "name": "Arquivo EditorConfig", + "description": "Cria um arquivo .editorconfig para configurar as preferências de estilo de código.", + "symbols/Empty/displayName": "Vazio", + "symbols/Empty/description": "Cria .editorconfig vazio em vez dos padrões para .NET." +} +``` + ## Pack a template into a NuGet package (nupkg file) A custom template is packed with the [dotnet pack](dotnet-pack.md) command and a *.csproj* file. Alternatively, [NuGet](/nuget/tools/nuget-exe-cli-reference) can be used with the [nuget pack](/nuget/tools/cli-ref-pack) command along with a *.nuspec* file. However, NuGet requires the .NET Framework on Windows and [Mono](https://www.mono-project.com/) on Linux and macOS. From 600c057bd274ef154f2cfd6f6b2de692103d8e16 Mon Sep 17 00:00:00 2001 From: Mariana Dematte Date: Wed, 18 Jan 2023 02:09:24 -0800 Subject: [PATCH 2/4] Suggested changes --- docs/core/tools/custom-templates.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/core/tools/custom-templates.md b/docs/core/tools/custom-templates.md index 585f79a4bc180..4f51aaaa4a9c6 100644 --- a/docs/core/tools/custom-templates.md +++ b/docs/core/tools/custom-templates.md @@ -91,31 +91,36 @@ The *template.json* file looks like the following: The *mytemplate* folder is an installable template package. Once the package is installed, the `shortName` can be used with the `dotnet new` command. For example, `dotnet new adatumconsole` would output the `console.cs` and `readme.txt` files to the current folder. -### Template localization +## Template localization + The .NET templates are localizable. If a template is localized for the language matching the current locale, its elements will appear in the same language as the CLI. Localization is optional when creating new templates. The localizable elements on a template are: + - Name - Author - Description - Symbols - Description - Display Name - - Descriptions and Diplay name of choices for choice paramemters + - Descriptions and Display name of choices for choice parameters - Post actions - - description + - Description - Manual instructions Localization files have a JSON format, and just one file per culture should exist. The naming convention is: `templatestrings..json`, where `lang code` corresponds to one of the [CultureInfo](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo.name) options. All localization files should be inside the `.template-config\localize` folder. The localization JSON consists of key value pairs: + - The key is the reference to an element of `template.json` to be localized. If the element is a child, use the full path with a `/` delimiter. - The value is the localization string of the element given by the key. For more information about localizing templates, see the [dotnet templating wiki's localization page](https://github.com/dotnet/templating/wiki/Localization). -#### Example -For example, here's *template.json* file with some localiable fields: +### Example + +For example, here's *template.json* file with some localizable fields: + ```JSON { "$schema": "http://json.schemastore.org/template", @@ -135,7 +140,7 @@ For example, here's *template.json* file with some localiable fields: } ``` -And some fields are to be localizes to Brazilian Portuguese. The filename will be `templatestrings.pt-BR.json` to match the culture, and it would look like: +And some fields are to be localized to Brazilian Portuguese. The filename will be `templatestrings.pt-BR.json` to match the culture, and it would look like: ```JSON { From af94de63341b90646652a3480ad6abd16813b9e4 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Wed, 18 Jan 2023 11:07:15 -0800 Subject: [PATCH 3/4] remove en-us from link --- docs/core/tools/custom-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/custom-templates.md b/docs/core/tools/custom-templates.md index 4f51aaaa4a9c6..3c25f28078946 100644 --- a/docs/core/tools/custom-templates.md +++ b/docs/core/tools/custom-templates.md @@ -108,7 +108,7 @@ The localizable elements on a template are: - Description - Manual instructions -Localization files have a JSON format, and just one file per culture should exist. The naming convention is: `templatestrings..json`, where `lang code` corresponds to one of the [CultureInfo](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo.name) options. All localization files should be inside the `.template-config\localize` folder. +Localization files have a JSON format, and just one file per culture should exist. The naming convention is: `templatestrings..json`, where `lang code` corresponds to one of the [CultureInfo](https://learn.microsoft.com/dotnet/api/system.globalization.cultureinfo.name) options. All localization files should be inside the `.template-config\localize` folder. The localization JSON consists of key value pairs: From 341a810830858ef0aa686bea385f0f243fe8b6e9 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Wed, 18 Jan 2023 11:28:58 -0800 Subject: [PATCH 4/4] Make link relative per build suggestion --- docs/core/tools/custom-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/custom-templates.md b/docs/core/tools/custom-templates.md index 3c25f28078946..d9ca759d984b0 100644 --- a/docs/core/tools/custom-templates.md +++ b/docs/core/tools/custom-templates.md @@ -108,7 +108,7 @@ The localizable elements on a template are: - Description - Manual instructions -Localization files have a JSON format, and just one file per culture should exist. The naming convention is: `templatestrings..json`, where `lang code` corresponds to one of the [CultureInfo](https://learn.microsoft.com/dotnet/api/system.globalization.cultureinfo.name) options. All localization files should be inside the `.template-config\localize` folder. +Localization files have a JSON format, and just one file per culture should exist. The naming convention is: `templatestrings..json`, where `lang code` corresponds to one of the [CultureInfo](/dotnet/api/system.globalization.cultureinfo.name) options. All localization files should be inside the `.template-config\localize` folder. The localization JSON consists of key value pairs: