README.md

![Coveralls](https://img.shields.io/coveralls/github/BartOtten/phoenix_localized_routes)
[![Build Status](https://github.com/BartOtten/phoenix_localized_routes/actions/workflows/elixir.yml/badge.svg?event=push)](https://github.com/BartOtten/phoenix_localized_routes/actions/workflows/elixir.yml)
[![Last Updated](https://img.shields.io/github/last-commit/BartOtten/phoenix_localized_routes.svg)](https://github.com/BartOtten/phoenix_localized_routes/commits/main)
[![Hex.pm](https://img.shields.io/hexpm/v/phoenix_localized_routes)](https://hex.pm/packages/phoenix_localized_routes)
![Hex.pm](https://img.shields.io/hexpm/l/phoenix_localized_routes)


# 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](#routes) (no mandatory _website.com/[locale]/page_)
- URLs can [match the language of content](#multilingual-routes); enhancing user
  engagement and content relevance.
- [Less than 10 lines](USAGE.md#helpers) of code to change in existing applications.
- Includes [helper functions](#route-helpers) to generate links to other locales.
- Supports [custom assigns](#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`](`mix gettext.extract`).
  - 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](https://hexdocs.pm/phoenix_localized_routes/) (stable)
and [GitHub Pages](https://bartotten.github.io/phoenix_localized_routes/) (development).

We also provide an [example application](#example-application) you can experiment with.

## Requirements and Installation

See the [Usage Guide](USAGE.md) 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](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveView.html#on_mount/1) 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.

``` bash
  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](http://localhost:4000/europe/nl/producten/).