The bundled i18n model (short for "internationalisation") lets one set of templates serve several languages. The text written in your templates is the default language; other languages come from small PHP dictionary files.

List the languages in application/config/the_app.php, default first:

config::set('languages')->to(array('en', 'ro'));

Use two- or three-letter language codes, optionally with a region (pt-br).

Wrap translatable text in print.i18n.<file>('<key>'):

<h1><!-- print.i18n.home('welcome') -->Welcome<!-- /print.i18n.home('welcome') --></h1>
<a href="menu.html"><!-- print.i18n.common('menu') -->Our menu<!-- /print.i18n.common('menu') --></a>

• home is the dictionary file, welcome the key.
• In the default language, and whenever a translation is missing, the template's text shows.

Create one file per language and dictionary name, in application/i18n/<language>/<file>.php, returning an array of key => text:

<?php // application/i18n/ro/home.php
return array(
    'welcome' => 'Bine ați venit',
);

<?php // application/i18n/ro/common.php
return array(
    'menu' => 'Meniul nostru',
);

Values may contain HTML. The i18n/ folder is never served over the web.

For each request, the first of these that gives one of your languages wins:

1. ?lang=ro in the address. The choice is remembered in a cookie.
2. The domain, if you map domains to languages:

   config::set('domain_language')->to(array('example.ro' => 'ro'));

   Subdomains count too: www.example.ro is Romanian. With the site's address set (RASTER_URL), the domains listed here are the site's own too: a page on example.ro keeps its language, its links stay on example.ro, and its forms are accepted. Only the domain exactly as listed counts for that, so list www.example.ro as well if visitors use it. Any other host gets the site's address.
3. The cookie from an earlier ?lang= choice. Its name is lang, or set your own with config::set('language_cookie')->to('site_lang').
4. The browser's preferred languages (Accept-Language header).
5. The default language, the first in your list.

The cookie is the only cookie a visitor gets without logging in, and only after they pick a language.

<html lang="<!-- print.i18n.language /-->">

<ul class="languages">
  <!-- render.i18n.languages -->
  <li><!-- print.+class.state --><!-- [email protected] --><a href="#"><!-- print.code -->en<!-- /print.code --></a><!-- /[email protected] --><!-- /print.+class.state --></li>
  <!-- /render.i18n.languages -->
</ul>

render.i18n.languages returns one row per language with code, url (the current page with ?lang=…) and state (active for the current one).

The dictionaries translate the text in your templates. CMS page fields and collections store one value per field. For content editors write in several languages, the usual approach is separate fields or collections per language, chosen in the template, or a separate app per language (see Pages and URLs).

• The page cache keeps one copy per language.
• A static export writes each additional language into its own folder (/ro/…), and the switcher links there.
• The in-page editor uses the page's language for its own buttons.
• From a model, i18n::detect() returns the current language code.