Add new tutorial for multilingual sites

Simple tutorial showing one pattern for creating a multilingual site in Hugo.
2024-11-21 20:46:30 -05:00 · 2015-06-07 15:26:06 +09:00 · 2015-06-07 15:26:06 +09:00 · 847ad36e45
commit 847ad36e45
parent cc9536ec46
2 changed files with 137 additions and 0 deletions
--- a/docs/content/tutorials/create-a-multilingual-site.md
+++ b/docs/content/tutorials/create-a-multilingual-site.md
@ -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.
--- a/docs/content/tutorials/migrate-from-jekyll.md
+++ b/docs/content/tutorials/migrate-from-jekyll.md
@ -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
 ---