项目作者: crbelaus

项目描述 :
Embedded translations for Elixir
高级语言: Elixir
项目地址: git://github.com/crbelaus/trans.git
创建时间: 2016-05-19T21:09:01Z
项目社区:https://github.com/crbelaus/trans

开源协议:Apache License 2.0

下载


Trans

Tests
Hex.pm

Trans provides a way to manage and query translations embedded into schemas
and removes the necessity of maintaining extra tables only for translation storage.
It is inspired by the great hstore translate
gem for Ruby.

Trans is published on hex.pm and the documentation
is also available online. Source code is available in this same
repository under the Apache2 License.

On April 17th, 2017, Trans was featured in HackerNoon

Optional Requirements

Having Ecto SQL and Postgrex in your application will allow you to use the Trans.QueryBuilder
component to generate database queries based on translated data. You can still
use the Trans.Translator component without those dependencies though.

  • Ecto SQL 3.0 or higher
  • PostgreSQL 9.4 or higher (since Trans leverages the JSONB datatype)

Why Trans?

The traditional approach to content internationalization consists on using an
additional table for each translatable schema. This table works only as a storage
for the original schema translations. For example, we may have a posts and
a posts_translations tables.

This approach has a few disadvantages:

  • It complicates the database schema because it creates extra tables that are
    coupled to the “main” ones.
  • It makes migrations and schemas more complicated, since we always have to keep
    the two tables in sync.
  • It requires constant JOINs in order to filter or fetch records along with their
    translations.

The approach used by Trans is based on modern RDBMSs support for unstructured
datatypes. Instead of storing the translations in a different table, each
translatable schema has an extra column that contains all of its translations.
This approach drastically reduces the number of required JOINs when filtering or
fetching records.

Trans is lightweight and modularized. The Trans module provides metadata
that is used by the Trans.Translator and Trans.QueryBuilder modules, which
implement the main functionality of this library.

Setup and Quickstart

Let’s say that we have an Article schema that contains texts in English and we want to translate it to other languages.

  1. defmodule MyApp.Article do
  2. use Ecto.Schema
  3. schema "articles" do
  4. field :title, :string
  5. field :body, :string
  6. end
  7. end

The first step would be to add a new JSONB column to the table so we can store the translations in it.

  1. defmodule MyApp.Repo.Migrations.AddTranslationsToArticles do
  2. use Ecto.Migration
  3. def change do
  4. alter table(:articles) do
  5. add :translations, :map
  6. end
  7. end
  8. end

Once we have the new database column, we can update the Article schema to include the translations.

  1. defmodule MyApp.Article do
  2. use Ecto.Schema
  3. use Trans, translates: [:title, :body], default_locale: :en
  4. schema "articles" do
  5. field :title, :string
  6. field :body, :string
  7. # This generates a MyApp.Article.Translations schema with a
  8. # MyApp.Article.Translations.Fields for :es and :fr
  9. translations [:es, :fr]
  10. end
  11. end

After doing this we can leverage the Trans.Translator and Trans.QueryBuilder modules to fetch and query translations from the database.

The translation storage can be done using normal Ecto.Changeset functions just like it would be done for any other fields or associations.

  1. defmodule MyApp.Article do
  2. def changeset(article, attrs \\ %{}) do
  3. article
  4. |> cast(attrs, [:title, :body])
  5. |> validate_required([:title, :body])
  6. |> cast_embed(:translations, with: &cast_translations/2)
  7. end
  8. defp cast_translations(translations, attrs \\ %{}) do
  9. translations
  10. |> cast(attrs, [])
  11. |> cast_embed(:es)
  12. |> cast_embed(:fr)
  13. end
  14. end
  15. # Then, anywhere in your code:
  16. changeset = MyApp.Article.changeset(article, %{
  17. translations: %{
  18. es: %{title: "title ES", body: "body ES"},
  19. fr: %{title: "title FR", body: "body FR"}
  20. }
  21. })

Customizing the translation container

By default Trans looks for a translations field that contains the translations. This is known as the “translation container”.

You can override the default translation container passing the container option to Trans. In the following example the translations will be stored in the transcriptions field.

  1. defmodule MyApp.Article do
  2. use Ecto.Schema
  3. use Trans, translates: [:title, :body], default_locale: :en, container: :transcriptions
  4. schema "articles" do
  5. field :title, :string
  6. field :body, :strings
  7. translations [:es, :fr]
  8. end
  9. end

Customizing the translation schemas

If you want to use your own translation module you can simply pass the build_field_schema: false option when using the translations macro.

  1. defmodule MyApp.Article do
  2. use Ecto.Schema
  3. use Trans, translates: [:title, :body], default_locale: :en
  4. defmodule Translations.Fields do
  5. use Ecto.Schema
  6. embedded_schema do
  7. field :title, :string
  8. field :body, :string
  9. end
  10. end
  11. schema "articles" do
  12. field :title, :string
  13. field :body, :string
  14. translations [:es, :fr], build_field_schema: false
  15. end
  16. end

Is Trans dead?

Trans has a slow release cadence, but that does not mean that it is dead. Trans can be considered as “done” in the sense that it does one thing and does it well.

New releases will happen when there are bugs or new changes. If the last release is from a long time ago you should take this as a sign of stability and maturity, not as a sign of abandonment.