View on GitHub

CrI18n: Crystal Internationalization

Quick Start | Developing With | Parameters & Aliases | Pluralization | Formatters

Crystal Internationalization

The cri18n shard provides an all inclusive library for developing internationalized crystal applications, taking advantage of crystal’s macro language to help streamline development and deployment to provide confidence in the quality of your service.

Now that that boilerplate is out of the way….

Installation

Add to your shards.yml file

dependencies:
  cr-i18n:
    github: crystal-community/cr-i18n

and run > shards install

Usage

Label Files

Label files can be written as yaml or json files, and all files in the same directory are considered part of the same language / locale. A typical label directory layout could be something like:

labels
├── root.yml
└── en
    ├── en.yml
    └── us
        └── us.yml

The root.yml file is intended to be populated by developers and represent the first place where labels exist. Labels are then split into Languages (e.g. en) and Locales (e.g. us), found in the directory name. The names of files in these directories don’t matter, and the directory name is case sensitive (i.e. labels/en/us corresponds to the locale en-us, which is different from lables/en/Us which corresponds to en-Us).

Labels within label files can be organized and named anyway that makes sense. For example, a root.yml could contain:

user_page:
  username: Username
  un_alias: "%(username): %{name}"
  email: Email
  given_name: First Name
  surname: Last Name
  greetings: Hello, %{name}!

Using in Crystal

require "cr-i18n"

CrI18n.compiler_load_labels("./path/to/labels")

And then throughout your application code, use the top level label macro for whenever you have a string that will be displayed to the user:

label(user_page.username) # => "Username"
label(user_page.greeting, name: "Troy") # => "Hello, Troy!"
label(user_page.un_alias, name: "tsornson") # => "Username: tsornson"

From here, check out the development page for more details on how cr-i18n can help you build faster without worrying if you forgot a label somewhere or not.