OP10 Localization - Multilingual Properties

OP10 Localization contains extension methods and helpers to easily set up a multilingual site based on a by convention naming of the PropertyAlias. Unlike other packages, OP10 Localization does not provide a custom property editor for multilingual properties but instead maps the property to a language based on the PropertyAlias.

How to use

After installing OP10 Localization you can create localized properties by naming the property alias with an underline and the languages two letter ISO code:

• propertyName_isoCode
• title_en
• title_de
• title_fr

For Umbraco to know the available languages, create all required languages in the Settings-Section. The first language is always the default unless the OPTEN:localization:defaultCulture appSetting is set in the web.config. The value of the setting can be the two letter ISO Code or the language name: "en" or "en-GB".

<add key="OPTEN:localization:defaultCulture" value="en-GB" />

Now you have to add hostnames to the root node. If you want to provide a site in English (default), French and German set following hostnames with associated cultures for the root node:

• http://hostname/ -> Set default culture (This is needed otherwise child nodes only have the urls /en/child, /de/child and /fr/child but if the user accesses the url /child/ he gets an error 404 and does not get redirected to the right culture)
• http://hostname/en -> Set en culture
• http://hostname/de -> Set de culture
• http://hostname/fr -> Set fr culture

After everything mentioned above is set up, the user will be redirected to the relevant hostname according to their browser language if they access a page witheout the /en, /de or /fr url part.

In your Code, you can now access the multilingual property based on the current language of the request with the IPublishedContent extension method GetLocalizedValue instead of GetPropertyValue.

There is also a way to check if a multilingual Property has a value like HasValue: HasLocalizedValue

Examples

Get localized property value:

• Model.Content.GetLocalizedValue<string>("content") - returns the content in the language of the request's thread culture. If property has no value fallback to the default culture.
• Model.Content.GetLocalizedValue<string>("content", "en") - returns the content in English. If property has no value fallback to the default culture.
• Model.Content.GetLocalizedValue<string>("content", true) - returns the content in English. If property has no value fallback recursively.
• Model.Content.GetLocalizedValue<string>("textstring", recurse: false, withFallback: false) - returns the content in the language of the request's thread culture. If property has no value return empty.

Get localized title (if the property alias is title_isoCode

• Model.Content.GetLocalizedTitle() - returns the title in the language of the request's thread culture. If property has no value fallback to the default language or Model.Content.Name.
• Model.Content.GetLocalizedTitle("en") - returns the title in English. If property has no value fallback to the default culture or Model.Content.Name.
• Model.Content.GetLocalizedTitle(true) - returns the title in the language of the request's thread culture. If property has no value fallback recursively.

Get localized Grid

• Model.Content.GetLocalizedGridHtml(Html, "grid") - returns the localized grid html of the specified propertyAlias
• Html.GetLocalizedGridHtml(Model.Content, "grid") - returns the localized grid html of the specified propertyAlias

Localized URLs

If you need to have localized URLs then create a new data type with the OPTEN.UrlAlias and add it to the document types which need to have localized urls (You don't have to create a property for each language).

The alias of the property needs to be optenUrlAlias.

The OPTEN.UrlAlias provides an input box for each language added in the settings section. You only have to type in a value if the url segment should differ from the default Umbraco one.

To get the localized url you can still use Umbraco's Model.Content.Url.

To get the url for a specific language you can use the extension method GetLocalizedUrl: Model.Content.GetLocalizedUrl("en")

Browser redirect

You can enable the browser language redirect in the web.config with <add key="OPTEN:localization:browserLanguageRedirect" value="true" />

Now all users that access the page without the language segment in the url will be redirected to the language based on their browser language.

• English user navigates to /about-us - gets redirected to /en/about-us
• German user navigates to /about-us - gets redirected to /de/ueber-uns (because of a defined urlAlias
• Italian user navigates to /about-us - gets redirected to /en/about-us (because the Italian culture is not defined and English is default)

Localized Controllers

To use localization in your custom API and Surface Controllers you have to to extend from LocalizedUmbracoApiController or LocalizedSurfaceController. You can also use the Attribute [Localized] on the controller.

For Localized API Controllers, you have to pass the language for the request. With jQuery you can do this like this:

$.ajaxSetup({
  headers: { "accept-language": "@Request.GetCurrentUICulture().Name" }
});

Localized Error 404

To have localized Error 404 set it up according to https://our.umbraco.org/forum/developers/razor/33761-Display-404-page-from-razor-code#comment-124021 and then add <add key="OPTEN:localization:404" value="true" /> to the web.config.

Version History

• 1.8.0
  - Fixed Localization Migration sort order of properties
• 1.7.0
  - display all the language names in english and not as nativename. Otherwise it is impossible to know which language a property is assigned to if the language is for example arabic
• 1.5.5
  - added possibility to use an alttemplate with urlAlias
  - added button to migrate property on doctype
  - migration dashboard improvements
• 1.5.3.9
  - Initial release