Add new tutorial for multilingual sites - hugo - [fork] hugo port for 9front
(HTM) git clone git@git.drkhsh.at/hugo.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Submodules
(DIR) README
(DIR) LICENSE
---
(DIR) commit 847ad36e45bc3d2bd486a33144aa7dccfa5aacb3
(DIR) parent cc9536ec46fe76697b7d1d3f95d40d7dc9d35bf5
(HTM) Author: Rick Cogley <rcogley@RickMBP.esolia.net>
Date: Sun, 7 Jun 2015 15:26:06 +0900
Add new tutorial for multilingual sites
Simple tutorial showing one pattern for creating a multilingual site in
Hugo.
Diffstat:
A docs/content/tutorials/create-a-mu… | 136 +++++++++++++++++++++++++++++++
M docs/content/tutorials/migrate-fro… | 1 +
2 files changed, 137 insertions(+), 0 deletions(-)
---
(DIR) diff --git 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.
(DIR) diff --git 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
---