hugo/docs/content/tutorials/create-a-multilingual-site.md at 3410007dca4012d1dea3a9d953b4d0a180f43e70

mirror of https://github.com/gohugoio/hugo.git synced 2024-11-14 20:37:55 -05:00

digitalcraftsman 3410007dca docs: List multilingual tpl vars and show menu creation

Fixes #2436

2016-09-16 15:37:12 +02:00

5.7 KiB

Raw Blame History

author

lastmod

date

linktitle

title

weight

Rick Cogley

2015-12-24

2015-07-08

Multilingual Site

main

parent
tutorials

/tutorials/migrate-from-jekyll

Create a Multilingual Site

Note: Since v0.17 Hugo has built-in support for the creation of multilingual website. [Read more about it]({{< relref "content/multilingual.md" >}}).

Introduction

Hugo allows you to create a multilingual site from its built-in tools. This tutorial will show one way to do it, and assumes:

You already know the basics about creating a Hugo site
You have a separate domain name for each language
You'll use /data files for some translation strings
You'll use single, combined layout and static folders
You'll use a subfolder for each language under content and public

Site Configs

Create your site configs in the root of your repository, for example for an English and Japanese site.

English Config config_en.toml:

baseurl = "http://acme.com/"
title = "Acme Inc."
contentdir = "content/en"
publishdir = "public/en"

[params]
    locale = "en-US"

Japanese Config config_ja.toml:

baseurl = "http://acme.jp/"
title = "有限会社アクミー"
contentdir = "content/ja"
publishdir = "public/ja"

[params]
    locale = "ja-JP"

If you had more domains and languages, you would just create more config files. The standard config.toml is what Hugo will run as a default, but since we're creating language-specific ones, you'll need to specify each config file when running hugo server or just hugo before deploying.

Prep Translation Strings in `/data`

Create .yaml (or .json or .toml) files for each language, under /data/translations.

English Strings en-US.yaml:

topslogan: Acme Inc.
topsubslogan: You'll love us
...

Japanese Strings ja-JP.yaml:

topslogan: 有限会社アクミー
topsubslogan: キット勝つぞ
...

In some cases, where there is more complex formatting within the strings you want to show, it might be better to employ some conditional logic in your template, to display a block of html per language.

Reference Strings in templates

Now you can reference the strings in your templates. One way is to do it like in this layouts/index.html, leveraging the fact that you have the locale set:

<!DOCTYPE html>
<html lang="{{ .Site.Params.locale }}">
...
  <head>
    <meta charset="utf-8">
    <title>{{ if eq .Site.Params.locale "en-US" }}{{ if .IsHome }}Welcome to {{ end }}{{ end }}{{ .Title }}{{ if eq .Site.Params.locale "ja-JP" }}{{ if .IsHome }}へようこそ{{ end }}{{ end }}{{ if ne .Title .Site.Title }} : {{ .Site.Title }}{{ end }}</title>
    ...
  </head>
  <body>
    <div class="container">
      <h1 class="header">{{ ( index $.Site.Data.translations $.Site.Params.locale ).topslogan }}</h1>
      <h3 class="subheader">{{ ( index $.Site.Data.translations $.Site.Params.locale ).topsubslogan }}</h3>
    </div>
  </body>
</html>

The above shows both techniques, using an if eq and else if eq to check the locale, and using index to pull strings from the data file that matches the locale set in the site's config file.

Customize Dates

At the time of this writing, Golang does not yet have support for internationalized locales, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like data/mois.yaml with this content:

1: "janvier"
2: "février"
3: "mars"
4: "avril"
5: "mai"
6: "juin"
7: "juillet"
8: "août"
9: "septembre"
10: "octobre"
11: "novembre"
12: "décembre"

... then index the non-English date names in your templates like so:

<time class="post-date" datetime="{{ .Date.Format "2006-01-02T15:04:05Z07:00" | safeHTML }}">
  Article publié le {{ .Date.Day }} {{ index $.Site.Data.mois (printf "%d" .Date.Month) }} {{ .Date.Year }} (dernière modification le {{ .Lastmod.Day }} {{ index $.Site.Data.mois (printf "%d" .Lastmod.Month) }} {{ .Lastmod.Year }})
</time>

This technique extracts the day, month and year by specifying .Date.Day, .Date.Month, and .Date.Year, and uses the month number as a key, when indexing the month name data file.

Create Multilingual Content

Now you can create markdown content in your languages, in the content/en and content/ja folders. The frontmatter stays the same on the key side, but the values would be set in each of the languages.

Run Hugo Server or Deploy Commands

Once you have things set up, you can run hugo server or hugo before deploying. You can create scripts to do it, or as shell functions. Here are sample basic zsh functions:

Live Reload with hugo server:

function hugoserver-com {
  cd /Users/me/dev/mainsite
  hugo server --buildDrafts --verbose --source="/Users/me/dev/mainsite" --config="/Users/me/dev/mainsite/config_en.toml" --port=1377
}
function hugoserver-jp {
  cd /Users/me/dev/mainsite
  hugo server --buildDrafts --verbose --source="/Users/me/dev/mainsite" --config="/Users/me/dev/mainsite/config_ja.toml" --port=1399
}

Deploy with hugo and rsync:

function hugodeploy-acmecom {
    rm -rf /tmp/acme.com
    hugo --config="/Users/me/dev/mainsite/config_en.toml" -s /Users/me/dev/mainsite/ -d /tmp/acme.com
    rsync -avze "ssh -p 22" --delete /tmp/acme.com/ me@mywebhost.com:/home/me/webapps/acme_com_site
}

function hugodeploy-acmejp {
    rm -rf /tmp/acme.jp
    hugo --config="/Users/me/dev/mainsite/config_ja.toml" -s /Users/me/dev/mainsite/ -d /tmp/acme.jp
    rsync -avze "ssh -p 22" --delete /tmp/acme.jp/ me@mywebhost.com:/home/me/webapps/acme_jp_site
}

Adjust to fit your situation, setting dns, your webserver config, and other settings as appropriate.

5.7 KiB Raw Blame History