Batman.js is no longer in production at Shopify and is not actively maintained.

This website is left for reference (and for old times' sake).

batman.js

Batman.I18N is a batman.js extra (available in CoffeeScript) for providing multi-langauge support in your application. It is modeled after Rails i18n.

To use Batman.I18N, you must:

For example:

# after including Batman.I18N
Batman.I18N.enable()

# define locales:
Batman.I18N.set 'locales.en',
  messages:
    welcome: "Welcome"
  account:
    sign_in: "Sign In"
    register: "Register"

Batman.I18N.set 'locales.zh'
  messages:
    welcome: '欢迎'

# get translations:
Batman.I18N.get("locale")    # "en", default
Batman.t("messages.welcome") # "Welcome"
Batman.I18N.set("locale", "zh")
Batman.t("messages.welcome") # "欢迎"

You can get translations for the current locale by using t in view bindings:

<p data-source='t.messages.welcome'></p>
  • Getting locales from the server

    Batman.I18N.get('locales') returns a Batman.I18N.LocalesStorage. This object's default accessor fetches locale objects from the server and caches them on the client. For example:

    Batman.I18N.get('locales.es')     # GET /locales/es.json
    Batman.I18N.get('locales.fr')     # GET /locales/fr.json

    Batman.I18N.translate will fetch a locale if it isn't loaded already:

    Batman.I18N.set('locale', 'zh')
    Batamn.I18N.translate('welcome')  # GET /locales/zh.json

    The Batman.Request expects a JSON response with the locale object:

    {
      "zh" : {
        "welcome" : "欢迎",
        "account" : {
          "sign_in" : "登录",
          "register" : "注册",
        }
      }
    }

    When the new values are returned, view bindings will be automatically updated.

  • Error messages

    You can provide error messages for a new locale by including translations in the same structure as batman.js's default messages. See the batman.js source for the structure of these messages.

  • @defaultLocale[= "en"] : String

    The default locale for Batman.I18N. Override this to make your app start in a locale other than "en".

  • @locale : String

    The current locale for Batman.I18N, used by Batman.translate. Set this value to change your locale:

    Batman.I18N.set('locale', 'fr') # Bienvenue!
  • @locales : I18N.LocalesStorage

    Returns the current Batman.I18N.LocalesStorage, which stores locales and there translations. You can set keys on locales to define translations:

    Batman.I18N.set("locales.uz", { ... })

    See "Getting locales from the server" for information about how Batman.I18N.LocalesStorage handles missing keys.

  • @translations : Object

    Returns the defined translations for the current locale.

  • @enable()

    Turns on Batman.I18N by:

    • Storing batman.js's default error messages to the "en" locale
    • Overriding Batman.translate to use Batman.I18N.translate
  • @disable()

    Turns off Batman.I18N by restoring previous functionality to Batman.translate.

  • @useFallback([=false]) : Boolean

    If set to true, translate will use translations from defaultLocale when a translation from the current locale isn't available.

Help us improve our documentation!

Contributions to this page are welcome on Github. If you find a problem but you cannot fix it, please open an issue.

Discussion regarding batman.js documentation is also welcome on our mailing list.