Locale-aware content

Amagaki has inbuilt support for generating localized pages, using localized URL
paths and supporting localized content. See the steps below to learn how to
generate localized pages.

Localized URL paths

To start with localization, create a page. Define its localization path
structure in front matter, and specify the locales it should be available in.

/content/pages/about.yaml

$path: /${doc.basename}/
$localization:
  path: /${doc.locale.id}/${doc.basename}/
  locales:
  - en
  - de
  - it

The above configuration will generate four pages, at the following URL paths:

/about/
/de/about/
/it/about/

Default locale

Within amagaki.ts, you can specify the pod's default locale. By default,
the default locale for all Amagaki projects is en. The default locale
indicates the "base" document, and it will not be included in localized paths.

Unique URL paths

Ensure that every localized path is unique. If two localized paths are
identical, Amagaki will raise an error.

Localized collections

You can localize all documents within a collection by specifying $localization
within the collection's _collection.yaml. In the below example, the $path
and $localization settings will be applied to all documents within the
/content/pages collection.

Settings can be overriden on a per-document basis.

/content/pages/_collection.yaml

$path: /${doc.basename}/
$localization:
  path: /${doc.locale.id}/${doc.basename}/
  locales:
  - en
  - de
  - it

Localized content

Now that you're generating localized pages, you can use the !IfLocale YAML
type to conditionally change content.

Let's say you want to change the hero copy in the de locale:

# ...
hero: !IfLocale
  default: !pod.string Hello World
  de: !pod.string Welcome to the site
# ...

In the above example, Amagaki will render "Hello World" for all locales, and
request the translation for "Welcome to the site" for locale de from
/content/locales/de.yaml.

NOTE: Avoid the common pitfall of including translated copy in YAML files.
Website translations should always be managed witin locales files. The
!IfLocale type is meant to vary source strings (or non-translated data), and
you should avoid storing translations within the documents.

Translations arrow_forward