mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-07 20:30:36 -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:
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:
|
||||
parent: tutorials
|
||||
prev: /tutorials/mathjax
|
||||
next: /tutorials/create-a-multilingual-site
|
||||
title: Migrate to Hugo from Jekyll
|
||||
weight: 10
|
||||
---
|
||||
|
|
Loading…
Reference in a new issue