|
1 | 1 | --- |
2 | | -meta.Title: Multilanguage setup in Umbraco |
3 | | -product: CMS |
4 | 2 | description: A guide to multilanguage setup in Umbraco |
5 | 3 | --- |
6 | 4 |
|
7 | 5 | # Creating a Multilingual Site |
8 | 6 |
|
9 | | -You can use **language variants** to setup a multilingual site. **Language Variants** allow you to have variants of the same content all under the same project. So, if you open a page and a language variant is enabled, you will see the option to switch the language from the drop-down list. Additionally, you can view or input the translated content. |
| 7 | +You can use **language variants** to set up a multilingual site. **Language Variants** allow you to have variants of the same content all under the same project. So, if you open a page and a language variant is enabled, you will see the option to switch the language from the drop-down list. Additionally, you can view or input the translated content. |
10 | 8 |
|
11 | | -This tutorial explains how to set-up a basic multilingual website. |
| 9 | +This tutorial explains how to set up a basic multilingual website. |
12 | 10 |
|
13 | 11 | ## Adding a New language |
14 | 12 |
|
@@ -226,3 +224,108 @@ For viewing purposes, I've added a stylesheet to my website. The final result sh |
226 | 224 | **German Version:** |
227 | 225 |
|
228 | 226 | <figure><img src="images/final-result-da.png" alt=""><figcaption></figcaption></figure> |
| 227 | + |
| 228 | +## Using Multiple languages across APIs |
| 229 | + |
| 230 | +When requesting content over an API, the culture will fall back to the default, unless explicitly set. |
| 231 | + |
| 232 | +To do this, you can use the IVariationContextAccessor. |
| 233 | + |
| 234 | +```csharp |
| 235 | +public class ExampleController : SurfaceController |
| 236 | +{ |
| 237 | + private readonly ILocalizationService _localizationService; |
| 238 | + private readonly IVariationContextAccessor _variationContextAccessor; |
| 239 | + |
| 240 | + public ExampleController(IUmbracoContextAccessor umbracoContextAccessor, IUmbracoDatabaseFactory databaseFactory, ServiceContext services, AppCaches appCaches, IProfilingLogger profilingLogger, IPublishedUrlProvider publishedUrlProvider, ILocalizationService localizationService, IVariationContextAccessor variationContextAccessor) : base(umbracoContextAccessor, databaseFactory, services, appCaches, profilingLogger, publishedUrlProvider) |
| 241 | + { |
| 242 | + _localizationService = localizationService; |
| 243 | + _variationContextAccessor = variationContextAccessor; |
| 244 | + } |
| 245 | + |
| 246 | + public IActionResult Index(string culture = null) |
| 247 | + { |
| 248 | + IEnumerable<ILanguage> UmbracoLanguages = _localizationService.GetAllLanguages(); //a helpful method to get all configured languages |
| 249 | + var requestedCulture = UmbracoLanguages.FirstOrDefault(l => l.IsoCode == culture); |
| 250 | + |
| 251 | + if (requestedCulture != null) |
| 252 | + { |
| 253 | + _variationContextAccessor.VariationContext = new VariationContext(requestedCulture.IsoCode); |
| 254 | + } |
| 255 | + |
| 256 | + //this will now be in the requested culture |
| 257 | + var content = UmbracoContext.Content.GetAtRoot(); |
| 258 | + |
| 259 | + //Content requested in this View Component will now be in the requested culture |
| 260 | + return ViewComponent(); |
| 261 | + } |
| 262 | +} |
| 263 | +``` |
| 264 | + |
| 265 | +### Creating a Language Switching Navigation |
| 266 | + |
| 267 | +To navigate between languages, we need to do two key things: |
| 268 | + |
| 269 | + 1. Get all the languages that the site can provide |
| 270 | + 2. Identify the language used on the current page |
| 271 | + |
| 272 | +Once you have these, you need to loop through the languages and provide links to each home node. |
| 273 | + |
| 274 | +### Getting all the languages for a site |
| 275 | + |
| 276 | +There are two ways to achieve this. One is to use `localizationService.GetAllLanguages();` to call the database, which is expensive and ideally includes caching. |
| 277 | + |
| 278 | +The alternative is to get the Home node and find all cultures associated with it. This has a few benefits including speed and providing us with a link to show the user. It is the process you will use when following this guide. |
| 279 | + |
| 280 | +### Identify the language for the current page |
| 281 | + |
| 282 | +This is achieved in `cs.html` files using `umbracoHelper.AssignedContentItem.GetCultureFromDomains();`. |
| 283 | + |
| 284 | +#### Steps |
| 285 | + |
| 286 | +Now that you have what you need, take the following steps to create a working example. |
| 287 | + |
| 288 | + 1. Create a new view called `Navigation.cshtml` |
| 289 | + 2. Paste in the following code: |
| 290 | + |
| 291 | +```cshtml |
| 292 | +@using Umbraco.Cms.Web.Common |
| 293 | +@inject IUmbracoHelperAccessor _umbracoHelperAccessor; |
| 294 | +
|
| 295 | +@{ |
| 296 | + _umbracoHelperAccessor.TryGetUmbracoHelper(out var umbracoHelper); |
| 297 | +
|
| 298 | + var homePage = umbracoHelper.ContentAtRoot().FirstOrDefault(c => c.ContentType.Alias == "{{homeNodeContentAlias}}"); |
| 299 | + var cultures = homePage?.Cultures; |
| 300 | +} |
| 301 | +
|
| 302 | +@if (cultures.Count > 1) |
| 303 | +{ |
| 304 | + <ul aria-label="Language switcher"> |
| 305 | + @foreach (var cult in cultures) |
| 306 | + { |
| 307 | + //get the settings for this culture |
| 308 | + System.Globalization.CultureInfo culture = new System.Globalization.CultureInfo(cult.Key); |
| 309 | + //if the current page has a language variant, otherwise link to the homepage language variant |
| 310 | + string langUrl = umbracoHelper.AssignedContentItem.Url(cult.Key, UrlMode.Relative) ?? homePage.Url(cult.Key, UrlMode.Relative); |
| 311 | +
|
| 312 | + <li> |
| 313 | + @if (cult.Key.ToLower() == umbracoHelper.AssignedContentItem.GetCultureFromDomains().ToLower()) |
| 314 | + { |
| 315 | + <span aria-current="true" >@culture.NativeName</span> |
| 316 | + } |
| 317 | + else |
| 318 | + { |
| 319 | + <a href="@langUrl" hreflang="@cult.Key" lang="@cult.Key" >@culture.NativeName</a> |
| 320 | + } |
| 321 | + </li> |
| 322 | + } |
| 323 | + </ul> |
| 324 | +} |
| 325 | +``` |
| 326 | + |
| 327 | + 3. Replace `{{homeNodeContentAlias}}` with the Document Type alias of your Home node. |
| 328 | + |
| 329 | +This will render links to either the language variant of the current page or the home node for the language variant. |
| 330 | + |
| 331 | +Additionally, `System.Globalization.CultureInfo` is used to obtain the native name of the language being rendered. This is useful if a user does not speak the default language. |
0 commit comments