Apostrophe 1.5: legacy documentation

Still using Apostrophe 1.5? Check out Apostrophe 2 for your future projects.

I18 N

Back to the Developer's Guide

Up to the Overview

Internationalization

Apostrophe supports internationalization and localization of sites in two critical ways: translation of the administrative interface, which your clients see, and translation of the actual site content, which end users of the site will see.

This section assumes familiarity with earlier sections of the manual (the Developer's Guide is optional).

What Languages Are Available?

Apostrophe supports UTF-8, so you can potentially translate your content into any language. At this time the user interface used by those editing content on the site supports French, Spanish, German and English, with more languages on the way. If you are editing site content in a language for which our administrative interface has not yet been translated, you'll see an administrative interface in English.

UTF-8 and Apostrophe

Apostrophe stores content in UTF-8 for compatibility with nearly all languages. However, the Apostrophe 1.0.x series has issues with generating slugs for items with non-Latin1 characters in their names. Support for this is already committed in the trunk and will be standard in the 1.1 series of Apostrophe. So those who wish to use Greek and other non-Latin character sets today should use the svn trunk of the plugin and migrate to the 1.1 stable branch when it appears.

In any case, for good results with non-ASCII characters you must ensure that your MySQL database is configured to store and collate information in UTF-8. See the databases.yml.sample file provided with Apostrophe for the required settings. Note the attribute settings below:

all:
  doctrine:
    class:        sfDoctrineDatabase
    param:
      dsn:        mysql:dbname=demo;host=localhost
      username: root
      password: root
      encoding: utf8
      attributes:
        DEFAULT_TABLE_TYPE: INNODB
        DEFAULT_TABLE_CHARSET: utf8
        DEFAULT_TABLE_COLLATE: utf8_general_ci

If you already have a database with the Latin1 character encoding or collation you will need to use ALTER TABLE statements to migrate it to UTF-8. See the MySQL documentation for more information on this issue.

To use UTF8 characters reliably in URLs with Symfony you must also modify your frontend_dev.php and index.php controllers to ignore PATH_INFO. Apache helpfully decodes UTF-8 URLs in PATH_INFO, unfortunately trashing them in the process. However Symfony is perfectly capable of getting by with just the REQUEST_URI environment variable, which it uses when there is no explicit PHP script name in the URL. So add this code to the top of your front end controllers (after the <? line of course) and you'll be ready to go with non-Latin URLs:

unset($_SERVER['PATH_INFO']);

Allowing Users to Switch Languages

By default, there is no user interface to switch languages in Apostrophe. You can turn this on easily with two app.yml settings: one to turn on the user interface and another to specify which languages are available. A third setting is required to fully internationalize search indexing, a step you may wish to skip if your site is used only in Latin languages because Zend Search is not able to be clever in its handling of plural versus singular words and the like when in strict UTF-8 mode.

Here is an example. Note that these steps have already been carried out in our current sandbox project.

all:
  a:
    # If true, there will be a language switcher next to the login/logout button
    i18n_switch: true
    i18n_languages: [en, fr, de, es]

You must also turn on support for internationalization in settings.yml, and may change the default language from English to another language there as well:

all:
  .settings:
    i18n: on
    default_culture: en

Be sure to symfony cc after this and any change to app.yml.

Then copy the apps/frontend/i18n folder from our sandbox project to your own project. This folder contains the apostrophe.fr.xml, apostrophe.de.xml, etc. files used to provide translation on the fly.

The language switcher can be used by both end users of the site and client staff who need to edit the site in a user interface that speaks their preferred language.

(Developers: if you don't care for the user interface of the language switcher, consider overriding the a/login partial at the application level. It is also a good candidate for progressive enhancement via jQuery.)

When you switch languages you will immediately notice that the home page has no content. Is this a bug? Not at all. The content has not been translated into the new language yet. That's the topic of the next section.

Translating Your Site Content

When you switch languages, you find yourself looking at a blank page. That's because the content has not yet been written for that page in that language. Just start adding slots!

Of course, you might want to use the content in another language as a starting point. We agree that this could be more convenient, however a handy workaround is to open a separate browser (Firefox if you use Chrome, and vice versa) and leave that browser logged into that site in the original language for reference. We'll be investigating ways to make this process easier, but the two-browsers method works very well in practice.

Adding the Culture to the URL

In order for Google to index content in several languages you will need distinct URLs for several languages. You can do this by changing your a_page route (beginning with Apostrophe 1.5):

a_page:
  url:   /:sf_culture/:slug
  param: { module: a, action: show }
  requirements: { slug: .* }

This allows Google to index separate pages for separate languages and allows links to language-specific pages to be shared by users.

This leads to the question, "how does Google ever see the home page in a language other than English?" Our default language switcher just changes the user's culture and redirects to the home page without a culture in the URL. But you can also access culture-specific homepages at /de/, /en/, /fr/ etc.

Consider removing the standard "homepage" route and replacing it with an action at the project level that redirects to the home page URL for the default language. Also consider adding direct links to the homepages for the other languages you support on your site. This will allow Google to find them.

Translating the User Interface Into a New Language

As with any Symfony project, internationalization of the user interface is accomplished via XLIFF files. And you can find complete translations in the apps/frontend/i18n folder of our sandbox project for several languages, including French, German, and Spanish. Install the sandbox project to see these in action right away. You can of course copy them to your own project's apps/frontend/i18n folder.

To add a new translation, you can take two approaches:

1.  Join the Apostrophe Now Google Group and express interest in translating the user interface. Our team will give you access to a convenient back end interface for translating the content, and your work will benefit the entire Apostrophe open source community.

2. Alternatively, just copy one of the existing XLIFF files in apps/frontend/i18n in our sandbox project, changing the language code to the appropriate 2-letter ISO code for your language, and get started translating. Those who are comfortable with XLIFF files may prefer this approach. Of course, we hope you will decide to share the results with the rest of the community.

Continue to Import & Migration

Up to Overview