Skip to content

Commit e975476

Browse files
sofietoftsofietoft
authored
Merge pull request #6360 from jonathoncove2/patch-1
Update adding-language-variants.md
2 parents 98619c3 + 0f5f0f6 commit e975476

File tree

3 files changed

+218
-4
lines changed

3 files changed

+218
-4
lines changed

‎10/umbraco-cms/tutorials/multilanguage-setup.md

Lines changed: 107 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
11
---
2-
meta.Title: Multilanguage setup in Umbraco
3-
product: CMS
42
description: A guide to multilanguage setup in Umbraco
53
---
64

75
# Creating a Multilingual Site
86

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.
108

11-
This tutorial explains how to set-up a basic multilingual website.
9+
This tutorial explains how to set up a basic multilingual website.
1210

1311
## Adding a New language
1412

@@ -226,3 +224,108 @@ For viewing purposes, I've added a stylesheet to my website. The final result sh
226224
**German Version:**
227225

228226
<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.

‎14/umbraco-cms/tutorials/creating-a-basic-website/adding-language-variants.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,3 +88,7 @@ To view the language variant on the browser, follow these steps:
8888
![Viewing the Language Variant Link](images/viewing-langvariant-browser-v14.png)
8989
5. Click on the link to view the new language node in the browser.
9090
6. Alternatively, you can add the domain name to your localhost in the browser. For example: [http://localhost:xxxx/da/](http:/localhost:xxxx/da/)
91+
92+
## More Information
93+
94+
Further information on multi-language setups can be found in the [Multilanguage Setup tutorial](../multilanguage-setup.md).

‎14/umbraco-cms/tutorials/multilanguage-setup.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -262,3 +262,110 @@ Danish Version:
262262
German Version:
263263

264264
<figure><img src="../../../10/umbraco-cms/tutorials/images/final-result-da.png" alt=""><figcaption></figcaption></figure>
265+
266+
## Using Multiple languages across APIs
267+
268+
When requesting content over an API, the culture will fall back to the default, unless explicitly set.
269+
270+
To do this, you can use the IVariationContextAccessor.
271+
272+
```csharp
273+
public class ExampleController : SurfaceController
274+
{
275+
private readonly ILanguageService _languageService;
276+
private readonly IVariationContextAccessor _variationContextAccessor;
277+
278+
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)
279+
{
280+
_localizationService = localizationService;
281+
_variationContextAccessor = variationContextAccessor;
282+
}
283+
284+
public IActionResult Index(string culture = null)
285+
{
286+
IEnumerable<ILanguage> UmbracoLanguages = _languageService.GetAllAsync().Result; //a helpful method to get all configured languages
287+
var requestedCulture = UmbracoLanguages.FirstOrDefault(l => l.IsoCode == culture);
288+
289+
if (requestedCulture != null)
290+
{
291+
_variationContextAccessor.VariationContext = new VariationContext(requestedCulture.IsoCode);
292+
}
293+
294+
//this will now be in the requested culture
295+
var content = UmbracoContext.Content.GetAtRoot();
296+
297+
//Content requested in this View Component will now be in the requested culture
298+
return ViewComponent();
299+
}
300+
}
301+
```
302+
303+
### Creating a Language Switching Navigation
304+
305+
To navigate between languages, you need to do two key things:
306+
307+
1. Get all the languages that the site can provide
308+
2. Identify the language used on the current page
309+
310+
Once you have these, you need to loop through the languages and provide links to each home node.
311+
312+
### Getting all the languages for a site
313+
314+
There are three ways to achieve this. The best one is to use `languageService.GetAllAsync();` which retrieves items from the cache.
315+
316+
Another is to use `localizationService.GetAllLanguages();` to call the database, which is expensive and ideally includes caching. This should only be done if you cannot use the ILanguage service. This service is marked as obsolete.
317+
318+
The alternative is to get the Home node and find all of the 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.
319+
320+
### Identify the language for the current page
321+
322+
This is achieved in `cs.html` files using `umbracoHelper.AssignedContentItem.GetCultureFromDomains();`
323+
324+
#### Steps
325+
326+
Now that you have what you need, take the following steps to create a working example.
327+
328+
1. Create a new view called `Navigation.cshtml`
329+
2. Paste in the following code:
330+
331+
```cshtml
332+
@using Umbraco.Cms.Web.Common
333+
@inject IUmbracoHelperAccessor _umbracoHelperAccessor;
334+
335+
@{
336+
_umbracoHelperAccessor.TryGetUmbracoHelper(out var umbracoHelper);
337+
338+
var homePage = umbracoHelper.ContentAtRoot().FirstOrDefault(c => c.ContentType.Alias == "{{homeNodeContentAlias}}");
339+
var cultures = homePage?.Cultures;
340+
}
341+
342+
@if (cultures.Count > 1)
343+
{
344+
<ul aria-label="Language switcher">
345+
@foreach (var cult in cultures)
346+
{
347+
//get the settings for this culture
348+
System.Globalization.CultureInfo culture = new System.Globalization.CultureInfo(cult.Key);
349+
//if the current page has a language variant, otherwise link to the homepage language variant
350+
string langUrl = umbracoHelper.AssignedContentItem.Url(cult.Key, UrlMode.Relative) ?? homePage.Url(cult.Key, UrlMode.Relative);
351+
352+
<li>
353+
@if (cult.Key.ToLower() == umbracoHelper.AssignedContentItem.GetCultureFromDomains().ToLower())
354+
{
355+
<span aria-current="true" >@culture.NativeName</span>
356+
}
357+
else
358+
{
359+
<a href="@langUrl" hreflang="@cult.Key" lang="@cult.Key" >@culture.NativeName</a>
360+
}
361+
</li>
362+
}
363+
</ul>
364+
}
365+
```
366+
367+
3. Replace `{{homeNodeContentAlias}}` with the Document Type alias of your Home node.
368+
369+
This will render links to either the language variant of the current page or the home node for the language variant.
370+
371+
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

Comments
 (0)