Open-Source Community

Localization (i18n)

The :i18n extension provides a way to localize your site. Activate it in your config.rb:

activate :i18n

By default this will search the locales folder in the root of your project
for YAML files representing each locale you want to support. The YAML file is a
set of keys and values for each string you need to localize in your site. The
keys, which is how you will refer to these strings in your templates, must be
the same in each locale, but the values will change. Here are two example YAML
files.

locales/en.yml:

---
en:
hello: "Hello"

locales/es.yml:

---
es:
hello: "Hola"

Localizable templates live in the source/localizable folder by default (see
below on how to change this option). Each template in that folder will have
access to the I18n helper. Using this helper, you can refer to keys from your
YAML files and inject the language-specific values into your template. Here's a
simple source/localizable/hello_world.html.erb template:

<%= I18n.t(:hello) %> World

This would output two files:

/hello_world.html with contents: "Hello World"

/es/hello_world.html with contents: "Hola World"

You can use t as a shortcut for I18n.t in your templates:

<%= t(:hello) %> World

Localized Paths

Each individual language is accessible in its own namespaced path. By default,
the first language lives at the root of the site (see below to change this
option). The default path is to simply use the language name (the name of the
YAML file) in the path:

/en/index.html
/es/index.html
/fr/index.html

You can change this with the :path option, but remember: the URL will always include the name of the YAML file:

activate :i18n, :path => "/langs/:locale/"

Now the paths would be:

/langs/en/index.html
/langs/es/index.html
/langs/fr/index.html

If you are unhappy using the YAML file names as part of your path, you can
remap them to different values.

Localizing Paths

In some cases you may want to localize the name of the file in addition to its
contents. You can use the special paths key in your language YAML files to
rename URLs to be language-specific.

Let's say we have a file source/localizable/hello.html.erb. By default, this
will output as:

/hello.html
/es/hello.html

If we want to rename that file to hola.html for Spanish only, we can use the
paths key in locales/es.yml:

---
es:
hello: "Hola"
paths:
hello: "hola"

Now, the files would be output as:

/hello.html
/es/hola.html

Localizable Templates

By default, the contents of source/localizable will be built in multiple
languages while the rest of your templates will continue to work normally. The
name of this folder can be changed with the :templates_dir option:

Manually specifying languages

If you'd prefer specify a list of supported languages rather than automatically
discovering files in locales/, you can use the :langs option:

activate :i18n, :langs => [:en] # Ignore all languages except :en

Default (Root) Language

By default, the first language (either specified by :langs or discovered in
your locales/ folder) will be the "default" language and will be mounted at
the root of your site. Given our two languages, files localized to :en will
be at the root:

source/localizable/index.html.erb

build/index.html is English

build/es/index.html is Spanish

You can change the default or disable mounting a specific language at the root
entirely using the :mount_at_root option:

Localizing Entire Templates

It can be inefficient to put translations of large blocks of text into the
locale YAML files. To help with this, Middleman offers a way to localize entire
templates. For example, if you had index.html, you could create two
templates, index.en.html.erb and index.es.html.erb. When the site is built,
you'll get:

build/index.html is English
build/es/index.html is Spanish

To use this localization method, be sure to put your files inside the localizable folder.