mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-21 20:46:30 -05:00
Add new tutorial for multilingual sites
Simple tutorial showing one pattern for creating a multilingual site in Hugo.
This commit is contained in:
Rick Cogley
Bjørn Erik Pedersen
parent
cc9536ec46
commit
847ad36e45
2 changed files with 137 additions and 0 deletions
136
docs/content/tutorials/create-a-multilingual-site.md
Normal file
136
docs/content/tutorials/create-a-multilingual-site.md
Normal file
|
|
@ -0,0 +1,136 @@
|
||||||
|
---
|
||||||
|
author: "Rick Cogley"
|
||||||
|
date: 2015-06-07
|
||||||
|
linktitle: Multilingual Site
|
||||||
|
menu:
|
||||||
|
main:
|
||||||
|
parent: tutorials
|
||||||
|
prev: /tutorials/migrate-from-jekyll
|
||||||
|
title: Create a Multilingual Site
|
||||||
|
weight: 10
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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`**:
|
||||||
|
|
||||||
|
~~~toml
|
||||||
|
baseurl = "http://acme.com/"
|
||||||
|
title = "Acme Inc."
|
||||||
|
contentdir = "content/en"
|
||||||
|
publishdir = "public/en"
|
||||||
|
...
|
||||||
|
[params]
|
||||||
|
locale = "en-US"
|
||||||
|
~~~
|
||||||
|
|
||||||
|
**Japanese Config `config_ja.toml`**:
|
||||||
|
|
||||||
|
~~~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`**:
|
||||||
|
|
||||||
|
~~~yaml
|
||||||
|
topslogan: Acme Inc.
|
||||||
|
topsubslogan: You'll love us
|
||||||
|
...
|
||||||
|
~~~
|
||||||
|
|
||||||
|
**Japanese Strings `ja-JP.yaml`**:
|
||||||
|
|
||||||
|
~~~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:
|
||||||
|
|
||||||
|
~~~html
|
||||||
|
<!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`**:
|
||||||
|
|
||||||
|
~~~shell
|
||||||
|
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`**:
|
||||||
|
|
||||||
|
~~~shell
|
||||||
|
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.
|
||||||
|
|
@ -6,6 +6,7 @@ menu:
|
||||||
main:
|
main:
|
||||||
parent: tutorials
|
parent: tutorials
|
||||||
prev: /tutorials/mathjax
|
prev: /tutorials/mathjax
|
||||||
|
next: /tutorials/create-a-multilingual-site
|
||||||
title: Migrate to Hugo from Jekyll
|
title: Migrate to Hugo from Jekyll
|
||||||
weight: 10
|
weight: 10
|
||||||
---
|
---
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue