Internationalization

Alchemy uses Rails I18n for all admin interface labels. Element names, ingredient labels, page layout names, hints, and menu names are all translatable through standard locale files.

How It Works

Create a file named config/locales/alchemy.en.yml (or any locale) in your app. Translations are scoped under the alchemy key:

# config/locales/alchemy.en.yml
en:
  alchemy:
    page_layout_names:
      blog: Blog
      blogpost: Blog Post
    element_names:
      post_header: Post Header
      post_text: Text Block
    ingredient_roles:
      headline: Headline
      body: Body Text

Alchemy automatically picks up these files. Your translations override the gem's defaults.

TIP

If no translation is found, Alchemy humanizes the key. For example, post_header becomes "Post header". You only need translations if the humanized version is not good enough.

Translation Scopes

Page Layout Names

en:
  alchemy:
    page_layout_names:
      standard: Standard Page
      blog: Blog Overview
      contact: Contact

Element Names

en:
  alchemy:
    element_names:
      article: Article
      post_header: Post Header
      contactform: Contact Form

Ingredient Roles

Ingredient labels can be translated globally or per element. Element-specific translations take precedence:

en:
  alchemy:
    ingredient_roles:
      # Global — used for all elements
      headline: Headline
      body: Body Text

      # Element-specific — overrides global for this element
      post_header:
        headline: Post Title

Menu Names

en:
  alchemy:
    menu_names:
      main_menu: Main Navigation
      footer_menu: Footer Navigation

Deprecation Notices

Elements and ingredients marked deprecated: true look up a translated notice. You can also pass a string directly.

# config/alchemy/elements.yml
- name: old_element
  deprecated: true

# config/locales/alchemy.en.yml
en:
  alchemy:
    element_deprecation_notices:
      old_element: Please use the new_element instead
    ingredient_deprecation_notices:
      old_role: This ingredient will be removed

Ingredient deprecation notices can also be scoped per element under ingredient_deprecation_notices.<element_name>.<role>.

Hints

Hints are tooltips shown next to elements and ingredients in the admin. You can set them directly in the YAML definition or translate them via locale files.

Inline hint in elements.yml:

- name: post_header
  hint: The header shown at the top of each blog post
  ingredients:
    - role: headline
      type: Text
      hint: Displayed as the page title and in the browser tab

Translated hint — set hint: true in the definition, then add the translation:

# config/alchemy/elements.yml
- name: post_header
  hint: true
  ingredients:
    - role: headline
      type: Text
      hint: true

# config/locales/alchemy.en.yml
en:
  alchemy:
    page_hints:
      blog: Overview page listing all blog posts
    element_hints:
      post_header: The header shown at the top of each blog post
    ingredient_hints:
      headline: Displayed as the page title and in the browser tab

TIP

Use translated hints when you need to support multiple languages in the admin interface. Use inline hints for single-language setups.

Default Ingredient Texts

Ingredients with a default value can use a symbol to look up translated default text:

# config/alchemy/elements.yml
- name: article
  ingredients:
    - role: body
      type: Richtext
      default: :lorem

# config/locales/alchemy.en.yml
en:
  alchemy:
    default_ingredient_texts:
      lorem: Lorem ipsum dolor sit amet...

Ingredient Groups

When ingredients are grouped in the element editor, the group headings are translatable. Like ingredient roles, they can be scoped per element:

en:
  alchemy:
    element_groups:
      # Global
      metadata: Metadata

      # Element-specific
      article:
        metadata: Article Metadata

Picture CSS Classes

CSS class labels for the Picture ingredient are translated under picture_ingredients.css_classes:

en:
  alchemy:
    picture_ingredients:
      css_classes:
        left: Left aligned
        right: Right aligned
        no_float: No float

Admin Localization

Alchemy ships with English translations only. The alchemy_i18n gem provides community-maintained translations for many languages. Add it to your Gemfile:

TIP

See Extensions for all available add-ons.

gem "alchemy_i18n"

You can also add your own translations or override existing ones. Alchemy detects available admin locales from files matching the alchemy.*.yml pattern:

# config/locales/alchemy.de.yml
de:
  alchemy:
    page_layout_names:
      blog: Blog
      blogpost: Blogartikel
    element_names:
      post_header: Artikelkopf
      post_text: Textblock
    ingredient_roles:
      headline: Überschrift
      body: Fließtext

Alchemy picks the admin locale from the first available match in this order:

1. The locale select in the admin interface
2. The user's preferred language (if the user model responds to language)
3. The browser's Accept-Language header
4. The app's I18n.default_locale

Using Alchemy.t

In your own code (views, controllers, helpers), use Alchemy.t to look up translations under the alchemy scope:

Alchemy.t(:save)
# => I18n.t(:save, scope: [:alchemy])

Alchemy.t(:headline, scope: :element_names)
# => I18n.t(:headline, scope: [:alchemy, :element_names])

For translations outside the Alchemy namespace, use the standard I18n.t helper.

Content Translation

Content translation (translating page content for visitors) is handled through Alchemy's multi-language system, not through I18n. Each language gets its own page tree with separate content. See the Languages guide for details.