U4-5777 - Allow Localization of Plugins without having to edit core language files

Created by Adrian Martin 10 Nov 2014, 17:06:44 Updated by Carlos Casalicchio 13 May 2016, 16:18:38

What did you do? Currently Creating Plugins requires editing of the core language files.

What did you expect to happen? Plugins language should merge from the plugins directory

I have working code based on umbraco 7.1.6 that merges the language file with the plugins' language files before sending it back to the client. This allows developers to create the language files without editing the core lang files. The new code supports caching and updates when any lang file is altered.


Adrian Martin 10 Nov 2014, 17:08:27

What do I do to get my code considered? Just fork in GitHub and submit?

Shannon Deminick 11 Nov 2014, 22:34:44


Per Ploug 17 Nov 2014, 14:48:19

Lets wait untill after 7.2 to merge this in

Flavio Spezi 12 Feb 2015, 09:15:18

Good idea, @Adrian.Martin !

Rusty Swayne 02 Mar 2015, 19:20:02

@Shandem An event like the ServerVariablesParser.Parsing event that we could add either a NodeList or IEnumerable ... something would be pretty slick.

NVM - your fix in your pull looks better =)

Shannon Deminick 15 Jun 2015, 15:19:23

Completed in rev: 6d9aba09526f1e2bf28f73db51f73de4f95bf178

Ok, here's how this all works

  • All supplementary language files MUST be named with the culture in the following format: languagecode-regioncode, Example: en-US.xml or da-DK.xml
  • All supplementary language files MUST be formatted in the normal Umbraco language file format with the exception that the root 'language' node does not require any attributes
  • For plugin developers, you can put language files in the : ~/App_Plugins/[MyPlugin]/Lang folder - any keys shipped with a plugin will NOT override the core default's if they match. Any custom keys shipped can be used as per normal in c# or js code.
  • For umbraco administrators: If you wish to override any values that are shipped with the core, you can now override these values without modifying the files shipped with the core. In the /Config/Lang/ folder there are now user language files named with a *.user.xml extension. For example: en-US.user.xml. Any keys that match the ones shipped with Umbraco will be overridden. Any keys not matching will be appended just like plugin language files. This will make it easier for admins to have any custom text they want for their end-users without having to worry about manipulating Umbraco files or re-merging them after upgrading.

Warren Buckley (Personal) 15 Jun 2015, 15:29:51

Hurray will make package developers very very happy with this change, with me included!

Flavio Spezi 15 Jun 2015, 16:52:00

It's a fantastic solution. Thanks!

Nicholas Westby 20 Jul 2015, 20:52:39

Awesome to see that this will finally be possible in Umbraco 7.3. FYI, I created an issue to request this functionality be documented: https://github.com/umbraco/Umbraco4Docs/issues/194

Timothy Lee Russell 22 Jul 2015, 16:11:42

Perfect! Thanks for this.

Timothy Lee Russell 07 Aug 2015, 18:23:13

One thing I noticed is that the xml files are not loaded (or merged) until after the administrator logs in?

For instance, I customized the login messages -- instead of "Happy Funky Friday", I changed the en-US.user.xml file to have a different value for that key. When I go to the login screen, it still says "Happy Funky Friday"...however, if I log in and then log back out, it now has my customized value.

But then, if I do a hard refresh of the login screen, it switches back to "Happy Funky Friday".

Shannon Deminick 17 Aug 2015, 14:45:48

I think that is perhaps because the default language is not en-US but en-GB

Shannon Deminick 17 Aug 2015, 14:48:36

Yup, i have confirmed it works, the default language is en-GB

Timothy Lee Russell 25 Aug 2015, 18:38:35

@Shandem Ok thanks, I see that is the case - if I instead customize the en-GB.user.xml file, the changes "take" on the login screen.

Question then, is it possible to switch the default language? I get that there needs to be a default but is it possible for me to change it to en-US? Sorry, no offense to the Brits but this is 'Merica. ;-)

Also, it seems weird that the default entry in a new install is "en-US" under languages but then the default thread culture is actually "en-GB".

At this point, I'm mostly just curious if it can be done - since we can certainly duplicate our customizations from en-US.user.xml into the en-GB.user.xml file and I've confirmed that it works fine.

I have specified the desired culture on the root nodes and on the host names and installed a browser plug-in to make sure the browser is passing Umbraco "en-US" as the culture.

I have tried setting the "umbracoDefaultUILanguage" key to both "en" and "en-US".

I have tried (unsuccessfully) in the web.config to add the globalization tag:

<system.web> </system.web>

I have tried (unsuccessfully) in the ApplicationStarted event of our plug-in (although I assume that this would happen too late in the lifecycle anyway.)

protected override void ApplicationStarted(UmbracoApplicationBase umbracoApplication, ApplicationContext applicationContext) { base.ApplicationStarted(umbracoApplication, applicationContext);

//TLR: culture seems to locked to en-GB so that the correct items are not pulled to the initial login screen //once you are logged in, it correctly localizes because the correct culture is specified on the user CultureInfo.CurrentCulture.ClearCachedData(); CultureInfo culture = CultureInfo.CreateSpecificCulture("en-US"); CultureInfo.DefaultThreadCurrentCulture = culture; CultureInfo.DefaultThreadCurrentUICulture = culture; Thread.CurrentThread.CurrentCulture = culture; Thread.CurrentThread.CurrentUICulture = culture; }

Shannon Deminick 26 Aug 2015, 07:57:11

@ttimothyleerussell yes i also had this question of setting the default :) I haven't had time to investigate just yet but something tells me it's not straight forward. I see that you've tried numerous things but just want to add some notes:

Setting the Thread culture is something that shouldn't be done, it is handled by Umbraco. Also in app started, that will only set the current thread - every single request is a new thread so setting it there will have no impact on any user.

Pretty sure Umbraco does not specifically uses the system.web/globalization setting for anything.

The 'umbracoDefaultUILanguage' setting is the interesting one, i have to look into the core to see what it is actually doing.

The way umbraco deals with the 2 letter and 4 letter cultures is pretty ugly due to legacy reasons dating back to probably the first version of Umbraco. We plan on fixing this in version 8 but until then we are stuck with this strangeness. Each language file in /umbraco/config/langs has a real 4 letter culture (i.e. en-GB) declared in it's XML, even though the file is named en.xml :( In 7.3 when using your custom user files, each file is named correctly (i.e. en-gb.user.xml). So the 2 letter language version that is stored in the db needs to translate to it's equivalent 4 letter real language code which is done by seeing what is configured in these files ... as i said it's not pretty but it's the way it currently works. For the en-US one, we store the full 4 letter code in the db (similarly we'd store the full 4 letter code for any language that would have an overlap with another 2 letter equivalent).

I will get back to you about the default language but it won't be for a week or so.

Timothy Lee Russell 26 Aug 2015, 17:15:30

Cool, thanks.

As far as trying the things that I did...I'll admit I was just throwing stuff at the wall to see if anything would stick.

We'll just customize the en-GB.user.xml file for keys that show up in the "default" state and call it good for now.

Carlos Casalicchio 13 May 2016, 16:18:38

@Shandem This is a great solution, but I haven't found anywhere how to customize the text for the login screen using en-US.user.xml Is there a tutorial (or documentation) anywhere?

Priority: Task - Pri 2

Type: Feature (request)

State: Fixed

Assignee: Shannon Deminick

Difficulty: Normal


Backwards Compatible: True

Fix Submitted: Pull request

Affected versions:

Due in version: 7.3.0


Story Points: