In this article, we’ll make the life of your users easier, by providing contents in their language.

Buffalo is a Go web development eco-system, designed to make the life of a Go web developer easier. It provides an advanced toolbox to allow people to write new apps in a fast but efficient way.

Internationalization

The aim of internationalization (or i18n) is to allow your application to provide its contents in the user’s language. Reading contents in your own language is easier, isn’t it?

Buffalo provides basic i18n support since v0.8.1, and advanced support since v0.10.2. You can now use the official i18n middleware, translation helpers and even Localized Views!

You can find the middleware here: https://github.com/gobuffalo/mw-i18n

The i18n middleware

A middleware is a piece of code executed before an action. It allows you to do some checks before executing the action, inject some data, and so on.

The Buffalo i18n middleware gets the current user language from a cookie, a session, HTTP headers or fallbacks to a defined language. It also defines helper functions, so you can translate your controllers and templates.

Here is the way to use it, in the app.go file:

var err error
if T, err = i18n.New(packr.NewBox(“../locales”), “en”); err != nil {
    app.Stop(err)
}
app.Use(T.Middleware())

The New method takes a packr box (so your translation strings can be embedded in the final binary), and a default language: here, the translations will be fetch from the locales directory at the root of the project; and the default language is english.

Manage translation strings

The i18n middleware is setup, so we need to provide translations for the languages we want to provide.

Translation files (or locales) are read from the locales directory, just like we saw it in the previous section. Each file in this folder follows the same norm:
filename.code.yaml

You can use the “filename” to split locales into modules (one for the users module, one for common strings, and so on). The code is the ISO code for the language (“fr” for French, “es” for Spanish), but variants are also supported (“en_us” for American English).

Here are sample yaml translation file contents (taken from gobuffalo.io repo):

English version:

# global.en.yaml
- id: head.title
  translation: Buffalo – Rapid Web Development in Go
- id: top.examples-tutorials
  translation: Examples & Tutorials

French version:

# global.fr.yaml
- id: head.title
  translation: Buffalo – Développement Web rapide en Go
- id: top.examples-tutorials
  translation: Exemples & tutoriels

Translation helpers

It’s time to use the translations in their context! The most common usage will be in the templates.

In templates

Buffalo ships with the Plush template engine: you can use the i18n helpers like that:

<%= t("greetings") %>

The i18n helper is called t by default, but you can change its name if you want. This function has a variadic signature, so it allows you to provide arguments:

<%= t("greetings-with-name", {name: "Stan"}) %>

Let’s say I’ve defined my translation file like that:

- id: greetings-with-name
  translation: Hello {{ .name }}!

The result here will be “Hello Stan!”.

In actions

You can also use the t helper in your actions (to set a translated version for flash messages, for instance). The same function is available as T.Translate:

func Login(c buffalo.Context) error {
  // [...]
  // Set a translated flash message
  c.Flash().Add("success", T.Translate(c, "users.login-success"))
  return c.Redirect(303, "/users/signin")
}

The only difference here is the first argument of the Translate function. The helper is the exact same function, but it sets the context argument for you.

Now, you have all the tools to translate your app. But in some cases, using helpers everywhere is not the best: if you manage a documentation (just like the gobuffalo.io website), it’s difficult to maintain the contents and keep it readable.

When your translation needs are intensive, or when you need to customize a page for different languages (let’s say you have a joke that can only work in English, so you want to drop it in the Spanish version), you can use the Localized Views.

Localized views

Buffalo provides a way to use a language suffix in the filename, when you want to have a different version for a specific language.

Let’s say the default version of your website is in English, but you want to have a different version for German visitors. In this case, you’ll create a first template in English.

index.html

<h1>This is my English homepage</h1>

In your browser, set German as the first accepted language. Then display the page.

Now, let’s create a new specific version for German:

index.de.html

<h1>Das ist mein Deutsch Hauptseite</h1><p>Custom contents for German people.</p>

Display the same URL in your browser:

Remove German as the first language in your browser, save, then refresh the page:

For further information about Buffalo translation features, you can read https://gobuffalo.io/docs/localization.

Happy translating!