Close
AlgoliaLogoLight
Close full mode
logo

Localization in Orchard Core CMS

Git RepositoryEdit on Github

Prerequisite

  • To learn localization in Orchard Core CMS, we will use an existing example from Create a custom Orchard Core CMS theme content.
  • Here is the current project structure:
    $ tree -I 'bin|obj|App_Data|Localization|wwwroot' orchard-example
    orchard-example
    └── src
    ├── OrchardExample.Web
    │ ├── NLog.config
    │ ├── OrchardExample.Web.csproj
    │ ├── Program.cs
    │ ├── Properties
    │ │ └── launchSettings.json
    │ ├── Startup.cs
    │ └── appsettings.json
    └── Themes
    └── OrchardExample.Theme
    ├── Manifest.cs
    ├── OrchardExample.Theme.csproj
    └── Views
    ├── Layout.cshtml
    └── _ViewImports.cshtml
  • Please note that you can use localization in both custom theme and module.

Create a PO file

  • Orchard Core CMS uses PO (portable object) file to store translation data.
  • We can create a PO file in multiple locations which are module, theme, tenant, App_Data and the root of the main project.
  • Learn more about PO file locations.
  • In this example, we will create a PO file in the root folder of the main project (OrchardExample.Web) with a file path /Localization/[CultureName].po.
  • Culture name is <language-code>-<country-code or region-code>. Example patterns are: th-TH, en-US. To learn more about globalization and localization terms, please check this document
  • Let's create a PO file /src/OrchardExample.Web/Localization/th-TH.po in orchard-example folder.
  • Here is the file structure after adding th-TH.po file.
$ tree -I 'bin|obj|wwwroot' orchard-example
orchard-example
└── src
├── OrchardExample.Web
│ ├── App_Data
│ ├── Localization
│ │ └── th-TH.po
│ ├── NLog.config
│ ├── OrchardExample.Web.csproj
│ ├── Program.cs
│ ├── Properties
│ │ └── launchSettings.json
│ ├── Startup.cs
│ └── appsettings.json
└── Themes
└── OrchardExample.Theme
├── Manifest.cs
├── OrchardExample.Theme.csproj
└── Views
├── Layout.cshtml
└── _ViewImports.cshtml
  • Add some translation data to th-TH.po file.
    msgid "Copyright"
    msgstr "สงวนลิขสิทธิ์"

Use a translation file

  • We can use this translation in a view (*.cshtml) by using T property and pass a value of msgid.

  • Edit Layout.cshtml an put the following code at the bottom.

    @T["Copyright"]
  • In addition, to use it in C# code, e.g. Service, Controller, Driver, Handler class, etc. Inject IStringLocalizer and use an instance as the following code:

    namespace OrchardExample.Module
    {
    public class HomeController : Controller {
    private readonly IStringLocalizer S;
    public HomeController(IStringLocalizer<HomeController> localizer) => S = localizer;
    public ActionResult Index() => View(S["Copyright"]));
    }
    }

Add supported cultures to Orchard Core CMS

  • Enable localization module. Go to admin panel > Configuration > Features > Search for "localization" and enable it.
  • Add supported cultures and set a default culture.
    1. Click Configuration.
    2. Click Localization.
    3. Click Culture.
    4. Select th-TH culture in a select list and click "Add culture". Do the same thing to add en-US culture.
    5. Set th-TH as a default culture.
    6. Click "Save".

localization configuration

Enable localization from code

"OrchardCore.Localization",

Test localization

  • Go back to frontend homepage. Append a query string ?culture=th-TH to an address in a browser and enter to reload the page.
  • You should find "Copyright" is displayed as "สงวนลิขสิทธิ์".

Troubleshooting if setting a default culture in admin panel does not take an effect.

  • This is because ASP.NET localization determines a culture by checking a culture value in these areas starting from:
    1. a query string which is &culture=culture-name
    2. value in a cookie
    3. Accept-Language HTTP header
    4. the DefaultRequestCulture property of the RequestLocalizationOptions class
    5. value of a thread's culture property
  • Orchard Core set a default culture as a DefaultRequestCulture property of the RequestLocalizationOptions class. OrchardCore.Localization/Startup.cs
  • If we don't have a culture value in query string or a cookie, a culture will be always a value of Accept-Language which sent by a browser and not a default culture that we set in an admin panel.
  • To make a culture get resolved to a default value in an admin panel, we need to adjust an order of how ASP.NET determine a culture by putting the following code in Start.cs of a custom module, theme or main project.
    // Startup.cs
    public override void ConfigureServices(IServiceCollection services)
    {
    services.Configure<RequestLocalizationOptions>(options =>
    {
    options.RequestCultureProviders.Clear(); // Clears all the default culture providers from the list
    options.RequestCultureProviders.Add(new QueryStringRequestCultureProvider());
    options.RequestCultureProviders.Add(new CookieRequestCultureProvider());
    // Later, the default culture value value will be set in
    // https://github.com/OrchardCMS/OrchardCore/blob/dev/src/OrchardCore.Modules/OrchardCore.Localization/Startup.cs#L45
    });
    }

Useful Orchard localization documents

Useful basic knowledge of localization in ASP.NET:

Loading comments...