Release version 3.0.0 (#82)

- Require Elixir 1.11 or newer
- Remove support for unstructured translations
- Add support for default locales and translation fallback chains
- Return `nil` for unitialised embed in struct
- Minor fixes, typos and dependency updates

.formatter.exs

@@ -1,5 +1,5 @@
 [
   inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"],
   import_deps: [:ecto],
-  locals_without_parens: [translations: 3, translations: 4]
+  locals_without_parens: [translations: 1, translations: 2]
 ]

.github/workflows/ci.yml

@@ -8,10 +8,8 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - elixir: 1.7
-            otp: 21
-          - elixir: 1.12
-            otp: 24
+          - elixir: 1.15.0
+            otp: 25.3
 
     env:
       MIX_ENV: test
@@ -29,7 +27,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       - name: Setup Elixir
         uses: erlef/setup-beam@v1
         with:

CHANGELOG.md

@@ -4,17 +4,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-# 2.3.0 - 2021-09-21
+# 3.0.0 - 2023-07-03 (requires Elixir 1.11 or newer)
+
+- Remove support for unstructured translations
+- Add support for default locales and translation fallback chains
+- Return `nil` for unitialised embed in struct
+- Minor fixes, typos and dependency updates
+
+# 2.3.0 - 2021-09-21 (requires Elixir 1.7 or newer)
 - Update dependencies to avoid compilation warnings
-- Require Elixir 1.7 or newer
 - Migrate from CircleCI to GitHub Actions
 - Allow translating entire structs
 - Add translate!/3 function to raise if a translation does not exist
 - Allow saving translations into embedded_schemas
 - Improve docs
 
-# 2.2.0 - 2020-02-01
-- Require Elixir 1.6 or newer
+# 2.2.0 - 2020-02-01 (requires Elixir 1.6 or newer)
 - Enable locale to be passed as a string
 - Update ExDoc dependency
 - Remove Faker dependency

README.md

@@ -52,9 +52,9 @@ that is used by the `Trans.Translator` and `Trans.QueryBuilder` modules, which
 implement the main functionality of this library.
 
 
-## Quickstart
+## Setup and Quickstart
 
-Imagine that we have an `Article` schema that we want to translate:
+Let's say that we have an `Article` schema that contains texts in English and we want to translate it to other languages.
 
 ```elixir
 defmodule MyApp.Article do
@@ -67,7 +67,7 @@ defmodule MyApp.Article do
 end
 ```
 
-The first step would be to add a new JSON column to the table so we can store the translations in it.
+The first step would be to add a new JSONB column to the table so we can store the translations in it.
 
 ```elixir
 defmodule MyApp.Repo.Migrations.AddTranslationsToArticles do
@@ -81,37 +81,99 @@ defmodule MyApp.Repo.Migrations.AddTranslationsToArticles do
 end
 ```
 
-Once we have the new database column, we can update the Article schema to include the translations
+Once we have the new database column, we can update the Article schema to include the translations.
 
 ```elixir
 defmodule MyApp.Article do
   use Ecto.Schema
-  use Trans, translates: [:title, :body]
+  use Trans, translates: [:title, :body], default_locale: :en
 
   schema "articles" do
     field :title, :string
     field :body, :string
-    embeds_one :translations, Translations, on_replace: :update, primary_key: false do
-      embeds_one :es, MyApp.Article.Translation, on_replace: :update
-      embeds_one :fr, MyApp.Article.Translation, on_replace: :update
-    end
+
+    # This generates a MyApp.Article.Translations schema with a
+    # MyApp.Article.Translations.Fields for :es and :fr
+    translations [:es, :fr]
+  end
+end
+```
+
+After doing this we can leverage the [Trans.Translator](https://hexdocs.pm/trans/Trans.Translator.html) and [Trans.QueryBuilder](https://hexdocs.pm/trans/Trans.QueryBuilder.html) 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.
+
+```elixir
+defmodule MyApp.Article do
+  def changeset(article, attrs \\ %{}) do
+    article
+    |> cast(attrs, [:title, :body])
+    |> validate_required([:title, :body])
+    |> cast_embed(:translations, with: &cast_translations/2)
+  end
+
+  defp cast_translations(translations, attrs \\ %{}) do
+    translations
+    |> cast(attrs, [])
+    |> cast_embed(:es)
+    |> cast_embed(:fr)
   end
 end
 
-defmodule MyApp.Article.Translation do
+# Then, anywhere in your code:
+changeset = MyApp.Article.changeset(article, %{
+  translations: %{
+    es: %{title: "title ES", body: "body ES"},
+    fr: %{title: "title FR", body: "body FR"}
+  }
+})
+```
+
+## 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.
+
+```elixir
+defmodule MyApp.Article do
   use Ecto.Schema
+  use Trans, translates: [:title, :body], default_locale: :en, container: :transcriptions
 
-  @primary_key false
-  embedded_schema do
+  schema "articles" do
     field :title, :string
-    field :body, :string
+    field :body, :strings
+    translations [:es, :fr]
   end
 end
 ```
 
-After doing this we can leverage the [Trans.Translator](https://hexdocs.pm/trans/Trans.Translator.html) and [Trans.QueryBuilder](https://hexdocs.pm/trans/Trans.QueryBuilder.html) modules to fetch and query translations from the database.
+## 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.
+
+```elixir
+defmodule MyApp.Article do
+  use Ecto.Schema
+  use Trans, translates: [:title, :body], default_locale: :en
 
-The translation storage can be done using normal `Ecto.Changeset` functions just like any other fields.
+  defmodule Translations.Fields do
+    use Ecto.Schema
+
+    embedded_schema do
+      field :title, :string
+      field :body, :string
+    end
+  end
+
+  schema "articles" do
+    field :title, :string
+    field :body, :string
+
+    translations [:es, :fr], build_field_schema: false
+  end
+end
+```
 
 
 ## Is Trans dead?

config/config.exs

@@ -1,6 +1,6 @@
 # This file is responsible for configuring your application
 # and its dependencies with the aid of the Mix.Config module.
-use Mix.Config
+import Config
 
 # This configuration is loaded before any dependency and is restricted
 # to this project. If another project depends on this project, this

config/test.ci.exs

@@ -1,4 +1,4 @@
-use Mix.Config
+import Config
 
 config :trans, Trans.Repo,
   username: "postgres",

config/test.sample.exs

@@ -1,4 +1,4 @@
-use Mix.Config
+import Config
 
 config :trans, Trans.Repo,
   username: "postgres",