docs: Add docs for lang.Merge

See #4463

docs/content/content-management/multilingual.md

@@ -178,11 +178,6 @@ You can also set the key used to link the translations explicitly in front matte
 translationKey: "my-story"
 ```
 
-
-{{% note %}}
-**Before Hugo 0.31**, the file's directory was not considered when looking for translations. This did not work when you named all of your content files, say, `index.md`. Now we use the full content path.
-{{% /note %}}
-
 If you need distinct URLs per language, you can set the slug in the non-default language file. For example, you can define a custom slug for a French translation in the front matter of `content/about.fr.md` as follows:
 
 ```yaml
@@ -192,6 +187,7 @@ slug: "a-propos"
 
 At render, Hugo will build both `/about/` and `/a-propos/` as properly linked translated pages.
 
+For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/).
 
 ## Link to Translated Content
 
@@ -354,7 +350,7 @@ The rendering of the main navigation works as usual. `.Site.Menus` will just con
 
 ```
 
-## Missing translations
+## Missing Translations
 
 If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
 
@@ -364,6 +360,8 @@ While translating a Hugo website, it can be handy to have a visual indicator of
 Hugo will generate your website with these missing translation placeholders. It might not be suited for production environments.
 {{% /note %}}
 
+For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/).
+
 ## Multilingual Themes support
 
 To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria:

docs/content/functions/lang.Merge.md

@@ -0,0 +1,47 @@
+---
+title: lang.Merge
+description: "Merge missing translations from other languages."
+godocref: ""
+workson: []
+date: 2018-03-16
+categories: [functions]
+keywords: [multilingual]
+menu:
+  docs:
+    parent: "functions"
+toc: false
+signature: ["lang.Merge FROM TO"]
+workson: []
+hugoversion:
+relatedfuncs: []
+deprecated: false
+draft: false
+aliases: []
+comments:
+---
+
+As an example:
+
+```bash
+{{ $pages := .Site.RegularPages | lang.Merge $frSite.RegularPages | lang.Merge $enSite.RegularPages }}
+```
+
+Will "fill in the gaps" in the current site with, from left to right, content from the French site, and lastly the English.
+
+
+A more practical example is to fill in the missing translations for the "minority languages" with content from the main language:
+
+
+```bash
+ {{ $pages := .Site.RegularPages }}
+ {{ .Scratch.Set "pages" $pages }}
+ {{ $mainSite := .Sites.First }}
+ {{ if ne $mainSite .Site }}
+    {{ .Scratch.Set "pages" ($pages | lang.Merge $mainSite.RegularPages) }}
+ {{ end }}
+ {{ $pages := .Scratch.Get "pages" }} 
+ ```
+
+{{% note %}}
+Note that the slightly ugly `.Scratch` construct will not be needed once this is fixed: https://github.com/golang/go/issues/10608
+{{% /note %}}