Phoenix Localized Routes

Localize your Phoenix website with multilingual URLs and custom template assigns; enhancing user engagement and content relevance.

                    ⇒ /products/:id/edit                  @loc.locale = "en_US"
/products/:id/edit  ⇒ /nederland/producten/:id/bewerken   @loc.locale = "nl_NL"
                    ⇒ /espana/producto/:id/editar         @loc.locale = "es_ES"

Top Features and Benefits

• URL format is customizable (no mandatory website.com/[locale]/page)
• URLs can match the language of content; enhancing user engagement and content relevance.
• Less than 10 lines of code to change in existing applications.
• Includes helper functions to generate links to other locales.
• Supports custom assigns per scope/locale.
• No run-time performance penalty!

Simple when possible, powerful where needed.

Usage Summary

• Add a configuration file describing which alternate routes to generate.
• Replace less than 10 lines of code in your existing Phoenix application.
• Optionally:
  • Run mix gettext.extract --merge.
  • Translate the URL parts like any other translatable text.
• Run mix phx.routes to verify the result.

You can now visit the localized URLs. Links and redirects in your application will automatically keep the visitors in their current (localized) scope.

Documentation

HexDocs (stable) and GitHub Pages (development).

We also provide an example application you can experiment with.

Requirements and Installation

See the Usage Guide for the requirements and installation instructions.

Working

A high-level overview of Phoenix Localized Routes' main features.

Routes

This library provides a localize/1 macro designed to wrap all route macros such as get/3, put/3 and resources/3. It replicates routes for each scope configured in a LocalizedRoutes backend module.

• each configured scope may have nested scopes.
• each configured scope may have custom assigns.
• routes may be translated.
• routes are locale independent (no mandatory website.com/[locale]/ format)

As a result, you have full control over the format, language and assigns of localized URLs.

Verified Routes

Phoenix Localized Routes uses a user-defined sigil (default: ~l) to support auto-localized paths and URLs. Each localized route is verified in the same way the original routes are.

Route Helpers

Phoenix Localized Routes creates locale aware replicas of the standard Phoenix helper functions to support auto-localized paths and URLs. It places those replicas in a new module named [MyAppWeb].Router.Helpers.Localized along with helpers for each locale to support linking to a specific locale.

The new module is a drop-in replacement of the standard Phoenix Helper module. Simply replace the MyAppWeb.Router.Helpers, as: Routes alias by MyAppWeb.Router.Helpers.Localized, as: Routes in myapp_web.ex.

As a result, all links to localized routes will respect the current scope of a visitor unless you decide otherwise.

Multilingual Routes

Phoenix Localized Routes extracts individual parts of a routes' path to a routes.po file for translation. At compile-time it combines the translated parts to create new routes.

As a result, users can enter URLs using localized terms which can enhance user engagement and content relevance.

Custom Assigns

Each scope can specify custom assigns. The customs assigns are available in templates as @loc (e.g.@loc.support_email).

In order to set the custom assigns for use in views and templates, this lib includes a Conn.Plug module and a LiveView helper module with on_mount callback. The modules create a bridge to share assigns between Phoenix Views and Phoenix Live Views.

As a result, using different assigns per locale is a matter of plug-and-play.

Example Application

An example Phoenix app using translated routes and custom assigns is available at GitHub.

  git clone https://github.com/BartOtten/phoenix_localized_routes_example.git
  cd phoenix_localized_routes_example
  iex -S mix phx.server

Once the application is running, have a look at the example page.