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

mirror of https://github.com/gohugoio/hugo.git synced 2024-11-21 20:46:30 -05:00

Rick Cogley 847ad36e45 Add new tutorial for multilingual sites

Simple tutorial showing one pattern for creating a multilingual site in
Hugo.

2015-06-16 12:17:09 +02:00

4.5 KiB

Raw Blame History

author

date

linktitle

title

weight

Rick Cogley

2015-06-07

Multilingual Site

main

parent
tutorials

/tutorials/migrate-from-jekyll

Create a Multilingual Site

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.

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

4.5 KiB Raw Blame History