Prerequisites

• Visual Studio Code installed on your machine
• Node.js version 20.17.0 installed on your machine (other versions of Node will likely work as well)
• General understanding of navigation in Visual Studio Code IDE

Steps

1. Open Visual Studio Code and create an empty folder “LocalizationExampleJS”:
   
   
    
2. Add the file “LocalizationExample.js” at the top level of your new folder:
   
   
    
3. Add a new subfolder "Resources" with empty files “en-US.json”, “es-MX.json”, and “fr-FR.json”:
   
   
   
   
4. Add the following code to each JSON translation file. It’s important for the text keys in all 3 files to be identical – in this case, the sample text we are using has the key “HelloWorld”.

en-US.json

<code>
{
  "HelloWorld": "Hello World!"
}
es-MX.json
{
  "HelloWorld": "¡Hola Mundo!"
}
fr-FR.json
{
  "HelloWorld": "Bonjour le monde!"
}
</code>

<code>
{
  "HelloWorld": "Hello World!"
}
es-MX.json
{
  "HelloWorld": "¡Hola Mundo!"
}
fr-FR.json
{
  "HelloWorld": "Bonjour le monde!"
}
</code>

5. Add the following code to “LocalizationExample.js”. This will enable you to supply a command line argument containing your desired locale string during testing. (Note that in an actual web frontend solution, the frontend code would need to access the current user’s culture from the server, NOT via command line argument.)

<code>
const args = process.argv.slice(2);
const currentCulture = args[0];
console.log("Your supplied culture is: " + currentCulture);
</code>

<code>
const args = process.argv.slice(2);
const currentCulture = args[0];
console.log("Your supplied culture is: " + currentCulture);
</code>

6. Below the code to extract current culture from command line arguments, add the following code to access the “HelloWorld” string for the supplied culture. If a culture is supplied that is not present in the application, then an error message will log accordingly, and the application will default to the “en-US” locale.

<code>
var pathToJson = "./Resources/" + args[0] + ".json";
try {
  const jsonObj = require(pathToJson);
  console.log(jsonObj.HelloWorld);
}
catch (err) {
  console.log("Culture \"" + currentCulture + "\" does not exist in this application - using default locale en-US.")
  pathToJson = "./Resources/en-US.json";
  const jsonObj = require(pathToJson);
  console.log(jsonObj.HelloWorld);
}
</code>

<code>
var pathToJson = "./Resources/" + args[0] + ".json";
try {
  const jsonObj = require(pathToJson);
  console.log(jsonObj.HelloWorld);
}
catch (err) {
  console.log("Culture \"" + currentCulture + "\" does not exist in this application - using default locale en-US.")
  pathToJson = "./Resources/en-US.json";
  const jsonObj = require(pathToJson);
  console.log(jsonObj.HelloWorld);
}
</code>

7. Your code is ready for testing! It should look something like this:

<code>
const args = process.argv.slice(2);
const currentCulture = args[0];
console.log("Your supplied culture is: " + currentCulture);

var pathToJson = "./Resources/" + args[0] + ".json";
try {
  const jsonObj = require(pathToJson);
  console.log(jsonObj.HelloWorld);
}
catch (err) {
  console.log("Culture \"" + currentCulture + "\" does not exist in this application - using default locale en-US.")
  pathToJson = "./Resources/en-US.json";
  const jsonObj = require(pathToJson);
  console.log(jsonObj.HelloWorld);
}
</code>

<code>
const args = process.argv.slice(2);
const currentCulture = args[0];
console.log("Your supplied culture is: " + currentCulture);

var pathToJson = "./Resources/" + args[0] + ".json";
try {
  const jsonObj = require(pathToJson);
  console.log(jsonObj.HelloWorld);
}
catch (err) {
  console.log("Culture \"" + currentCulture + "\" does not exist in this application - using default locale en-US.")
  pathToJson = "./Resources/en-US.json";
  const jsonObj = require(pathToJson);
  console.log(jsonObj.HelloWorld);
}
</code>

8. Open a terminal and test out the LocalizationExample solution using the command node .\LocalizationExample.js xx-XX, where “xx-XX” is a locale string representing the combination of a language and a region. Try out “es-MX”, “fr-FR”, “en-US”, and “pt-BR” (Brazilian Portuguese) as command line arguments.
   
   Note that the HelloWorld resource for the cultures “en-US”, “es-MX”, and “fr-FR” all appear translated as expected. However, the “pt-BR” locale yields the HelloWorld string in English, because this culture is not present in the collection of translations, and our code explicitly defaults to the “en-US” U.S. English locale in this case.

Localization Tips and Tricks

When it comes to localization, there is a lot more to consider than simply translating text and accessing it appropriately from code. Read on to learn some tips and tricks for elevating your localization solution!

Text Key Organization

Generally, DMC has found that it is beneficial to organize text keys into separate files based not only on language, but also based on what page of your application the text belongs on. For backend localization, this is likely best done by splitting text by controller. Here is an example of a backend localization file structure that includes two controllers, “Login.cs” and “Home.cs”, and two cultures, a default culture and “es-MX”:

• Resources folder
  • Login folder
    • Login.resx
    • Login.es-MX.resx
  • Home folder
    • Home.resx
    • Home.es-MX.resx

This separation organizes your translated text in a way that is easily modifiable for each individual page of your application.

In the event that identical text appears in multiple places in your application in English, it is still beneficial to duplicate that text key/value entry across pages, rather than maintaining a single key/value item. For example, if the word “Email” exists on both the “Login” and “Home” pages in the example above, this text key/value should exist in both the “Login” resource files and “Home” resource files. This enables you to update the text in one place without modifying the same text elsewhere, if desired. Also, translations of the same English word or phrase could be different across different languages, depending on the context of how the word or phrase is used – in this case, separate text/key values are necessary for translators to appropriately translate your application text.

Variables and Pluralization

Variables and pluralization can be quite tricky to handle in any localization solution. For a backend solution with .resx files, if you have a sentence to translate with a variable in the middle, you need to separate any given string key/value into separate parts that precede and follow the variable.

For example, say you want to include the phrase “Hello, {name} – welcome to my site!” The following key/value structure would need to be implemented in each .resx file to handle this phrase:

Additionally, numeric variables add an extra layer of complexity to a localization solution, because pluralization must be implemented for these. The way words are pluralized can actually differ significantly across languages. For example, Slavic languages (e.g. Russian, Czech) have a different style of pluralization for 5 or more of an item than they do for zero, one, or 2-4 items. So a solution that translates to Slavic languages must implement separate logic for pluralizing 5+ items than for other items. For example, the sentence “You have {number} items in your cart!” may have a key/value structure like this in English:

As you can see, this is a complex case to translate for – there are 8 total key/value pairs to accommodate just one sentence that integrates a numeric variable. To avoid the need for this, one solution is to reduce or eliminate the need for accommodating plurals – for example, you could rephrase “You have {number} items in your cart!” to instead become “Number of Items in Cart: {number}”. This would only require one key/value pair to be translated instead of eight.

Fallback Cultures

When a user’s specific locale does not have a translation present in your application, it can be beneficial to implement fallback cultures so this user is given a more suitable approximation of their desired language. For example, say a Spanish speaker lives in Spain and therefore has their browser locale set to “es-ES”. However, your application only has resources for Mexican Spanish “es-MX”. Ideally this person in Spain would see the application in Mexican Spanish rather than the application default of English, because Mexican Spanish more closely matches their desired language than English does.

Using .NET backend localization, fallback cultures can be implemented by simply renaming any files ending in “es-MX.resx” to instead end in “es.resx”. Per .NET’s culture fallback scenarios, upon receiving a request from the Spain Spanish user, .NET will still search for “es-ES” first. But upon not finding this specific culture, .NET will “fall back” to just the “es” portion of the locale string and will access the text as it exists in this new general Spanish file. Users using Mexican Spanish “es-MX” will see the same behavior.

Common Pitfalls

Localization can be complicated, and there are some common pitfalls you may encounter if you are implementing your own localization solution. Here are some examples:

• Logging / error messaging: if you are displaying raw exception messages to your users, then these are not able to be localized because they are generally hardcoded in English by the entities providing the error messages. In this case, your application should be updated to display custom error messages to your users instead of raw messages.
• Identifying EVERY source of user-facing text: There are many possible sources of text in your application that can go unnoticed, which can then become difficult to handle late in the localization process. Some examples are images, email templates, and messages from external libraries/packages/APIs. If you are doing frontend only localization, then it becomes necessary to make 100% certain that there is NO user facing text coming from the backend – if you discover late in the process that some user facing text comes from the server, then some “hacky” solutions may be necessary to preserve the frontend-only localization scheme.
• Not enforcing a single source of truth for text: If there is not a very solid system in place for establishing and updating the “source or truth” for translated text, then the localization process can quickly become messy. Things are always changing during development, and if there is not an established system to deliver text updates to translators and other stakeholders, then any one party can modify text without other stakeholders’ knowledge and introduce confusion. Enforce a single source of truth for text that all stakeholders can agree on. (Resource files are likely NOT the appropriate single source of truth, since non-developer stakeholders should also have control over text in the application.)

The post Basic JavaScript Localization Setup Using JSON with Visual Studio Code appeared first on DMC, Inc..

Often, software engineers refer to localization to mean simply translating an application into multiple languages. But in reality, localization can be much more involved than basic text translation. When localizing an application, these can all be items a software engineer needs to consider:

• Translation of user-facing text
• Date formatting
• Currency formatting
• Number formatting
• Text ordering and direction
• Images and other content
• Regional language differences
• And others

Every localization system is different, but in general, localization solutions should NOT solely consider target languages. Rather, to target a specific group of users, locales should be used. A locale combines language (what language the target users speak) with region (the area of the world in which the target users live). Region and language can be combined to form a locale string, generally in the format “xx-XX”, where “xx” is a two-letter code indicating the language and “XX” is a two-letter code indicating the region. Here are some examples of locale strings:

• en-US: English as spoken in the United States
• en-GB: English as spoken in United Kingdom of Great Britain and Northern Ireland
• pt-BR: Portuguese as spoken in Brazil
• pt-PL: Portuguese as spoken in Portugal
• es-MX: Spanish as spoken in Mexico
• es-US: Spanish as spoken in the United States

Language abbreviations are standardized using the ISO 639-1 language codes, and country abbreviations are standardized using the ISO 3166-1 alpha-2 country codes. A combination of codes from these two lists forms a complete locale, used to uniquely identify resources used for a language and region.

Successfully implementing an efficient and maintainable localization system involves significant upfront planning, for both software solution structure and communication with text stakeholders and translators.

Basic Localization Setup in .NET 8 with Visual Studio

This section will demonstrate how to set up basic localization in .NET 8 and Visual Studio Code. We will create a .NET 8 solution, and then we will modify the solution to include localization for two additional cultures (Spanish as spoken in Mexico “es-MX” and French as spoken in France “fr-FR”).

Note that programmatically, Microsoft uses the terminology “culture” rather than “locale” to indicate a combination of region and language that an application must be localized to.

Prerequisites

• Visual Studio 2022 installed on your machine
• .NET 8.0 SDK installed on your machine
• General understanding of navigation for Visual Studio IDE

Localization Steps

1. In Visual Studio 2022, create a new .NET 8 console application named LocalizationExample.

Once the project is created and opened in Visual Studio, it will look like this:

2. In the Visual Studio Package Manager Console, run the following commands to install necessary packages:
   1. Install-Package Microsoft.Extensions.Hosting
   2. Install-Package Microsoft.Extensions.DependencyInjection
   3. Install-Package Microsoft.Extensions.Localization

3. To set up localization with dependency injection, replace the contents of Program.cs with the following lines of code, which add the services required for localizing your application. Note that the specified ResourcePath is “Resources” – you will add this path to your project in the next step.

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;

using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddLocalization(options =>
        {
            options.ResourcesPath = "Resources";
        });
    })
    .Build();
Console.WriteLine("Hello, World!");

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;

using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddLocalization(options =>
        {
            options.ResourcesPath = "Resources";
        });
    })
    .Build();
Console.WriteLine("Hello, World!");

4. In the LocalizationExample project, add a new folder called “Resources”. This directory is where the localization services are set up to search for your localization resource files that will contain your localized text.

5. In the “Resources” folder, add a new item using the “Resources” type template. Name it “SampleResource.resx”.

When “SampleResource.resx” opens, you should see a table open with the columns “Name”, “Value”, and “Comment”. You will also see a dropdown at the top of the file with “Strings” selected – for this exercise you will preserve the “Strings” option, but other resource types can be localized by changing this dropdown. The resource file columns serve the following purposes:

1. Name: a string that uniquely identifies the piece of text the entry contains in the.resx files preceded with “SampleResource”. Note that it cannot begin with a number and cannot contain spaces or most special characters.
2. Value: The string value that corresponds to the Name key for the culture associated with this resource file.
3. Comment: An optional text entry to clarify information about the resource entry.

6. Repeat step 5 to create files “SampleResource.es-MX.resx” and “SampleResource.fr-FR.resx”.

7. Add the following entries to the .resx files created in steps 5-6. These values are “Hello World!” in different languages. Note that the file SampleResource.resx is the default resource file – if a culture is selected that does NOT match “fr-FR” or “es-MX” when the resource is accessed, then the application will default to the English value stored in SampleResource.resx.

8. Add the following code to Program.cs under the existing usings. This will enable the desired culture to be supplied as a command line argument, as well as add the appropriate using to use our new SampleResource files:

using System.Globalization; 
if (args is { Length: 1 })
{
    CultureInfo.CurrentCulture =
        CultureInfo.CurrentUICulture =
            CultureInfo.GetCultureInfo(args[0]);
}

using System.Globalization; 
if (args is { Length: 1 })
{
    CultureInfo.CurrentCulture =
        CultureInfo.CurrentUICulture =
            CultureInfo.GetCultureInfo(args[0]);
}

9. In Program.cs, replace the line Console.WriteLine("Hello, World!"); with Console.WriteLine(SampleResource.HelloWorld);. Your Program.cs should now look like this:

10. Build the solution by right clicking on the solution in the Solution Explorer and clicking “Build Solution”.

11. Open the .NET CLI / Terminal through the View menu.

12. Finally, test out the LocalizationExample solution via the newly opened terminal using the command dotnet run –project LocalizationExample.csproj xx-XX, where “xx-XX” is a combination of a language and a region. Try out “es-MX”, “fr-FR”, “en-US” (U.S. English), and “pt-BR” (Brazilian Portuguese) as command line arguments.

Note that the HelloWorld resource for the cultures “es-MX” and “fr-FR” both appear translated as expected. When .NET reaches into the Resources folder to obtain the “HelloWorld” resource, it uses the culture string associated with the stored CultureInfo.CurrentCulture to access the appropriate .resx file. However, the “en-US” and “pt-BR” cultures both yield the HelloWorld string in English, because neither of these cultures are explicitly provided for the SampleResource resource, and so .NET defaults to the base SampleResource.resx.

DMC is a full-service application development company focused on custom web, mobile, cloud, and desktop applications.  Contact us today to discuss your application development needs.

The post Basic Localization Setup in .NET 8 with Visual Studio appeared first on DMC, Inc..