User-friendly translations manager for Elixir/Phoenix projects.
View Demo · Report Bug · Request Feature

About The Project
Getting Started
Features
Plugins
Roadmap
Contributing
License
Contact
Acknowledgments

Note: Official documentation for Kanta library is available on hexdocs.

About The Project

If you're working on an Elixir/Phoenix project and need to manage translations, you know how time-consuming and error-prone it can be. That's where Kanta comes in. Our tool simplifies the process of managing translations by providing an intuitive interface for adding, editing, and deleting translations. Our tool also makes it easy to keep translations up-to-date as your project evolves. With Kanta, you can streamline your workflow and focus on building great software, not managing translations.

(back to top)

Getting Started

Prerequisites

Elixir (tested on 1.14.0)
Phoenix (tested on 1.7.0)
Ecto SQL (tested on 3.6)

Installation

The package can be installed by adding kanta to your list of dependencies in mix.exs:

def deps do
  [
    {:kanta, "~> 0.4.1"},
    {:gettext, git: "git@github.com:ravensiris/gettext.git", branch: "runtime-gettext"}
  ]
end

The dependency on this specific gettext version is because this library depends on an in-progress feature, to be included in a future release of gettext (see discussion in elixir-gettext/gettext#280 and pull request elixir-gettext/gettext#305). As of March 2023, this has been approved by an Elixir core team member, so we are eagerly awaiting for it being merged upstream.

Configuration

Add to config/config.exs file:

# config/config.exs
config :my_app, Kanta,
  endpoint: MyAppWeb.Endpoint, # Your app Endpoint module
  repo: MyApp.Repo, # Your app Repo module
  otp_name: :my_app, # Name of your OTP app
  plugins: []

Ecto repo module is used mostly for translations persistency. We also need endpoint to use VerifiedRoutes and project_root to locate the project's .po files.

Database migrations

Migrations is heavily inspired by the Oban approach. To add to the project tables necessary for the operation of Kanta and responsible for storing translations create migration with:

mix ecto.gen.migration add_kanta_translations_table

Open the generated migration file and set up up and down functions:

defmodule MyApp.Repo.Migrations.AddKantaTranslationsTable do
  use Ecto.Migration

  def up do
    Kanta.Migration.up(version: 2, prefix: prefix()) # Prefix is needed if you are using multitenancy with i.e. triplex
  end

  def down do
    Kanta.Migration.down(version: 2, prefix: prefix()) # Prefix is needed if you are using multitenancy with i.e. triplex
  end
end

after that run

mix ecto.migrate

Gettext module

We now need to pass information to our project's Gettext module that we want Kanta to manage translations. To do this add Kanta.Gettext.Repo as a default translation repository inside your Gettext module.

use Gettext, ..., repo: Kanta.Gettext.Repo

Kanta Supervisor

In the application.ex file of our project, we add Kanta and its configuration to the list of processes.

  def start(_type, _args) do
    children = [
      ...
      {Kanta, Application.fetch_env!(:my_app, Kanta)}
      ...
    ]
    ...
  end

Kanta UI

Inside your router.ex file we need to connect the Kanta panel using the kanta_dashboard macro.

import KantaWeb.Router

scope "/" do
  pipe_through :browser

  kanta_dashboard("/kanta")
end

(back to top)

Features

Extracting from PO files

Kanta is based on the Phoenix Framework's default localization tool, GNU gettext. The process, which runs at application startup, analyzes .po files with messages and converts them to a format for convenient use with Ecto and Kanta itself.

Storing messages in the database

Messages and translations from .po files are stored in tables created by the Kanta.Migration module. This allows easy viewing and modification of messages from the Kanta UI or directly from database tools. The caching mechanism prevents constant requests to the database when downloading translations, so you don't have to worry about a delay in application performance.

Translation progress

Kanta tracks the progress of your application's translation into other languages and reports it in the user's dashboard. In the dashboard you can filter your messages by domain or context, or use a search engine. It is also possible to display only the messages that need translation to better see how much work remains to be done.

(back to top)

Plugins

DeepL

Not all of us are polyglots, and sometimes we need the help of machine translation tools. For this reason, we have provided plug-ins for communication with external services that will allow you to translate texts into another language without knowing it. As a first step, we introduced integration with DeepL API offering 500,000 characters/month for free and more in paid plans. To use DeepL API add {:kanta_deep_l_plugin, "~> 0.1.1"} to your deps and append Kanta.DeepL.Plugin to the list of plugins along with the API key from your account at DeepL. New features will then be added to the Kanta UI that will allow you to translate using this tool.

# mix.exs
defp deps do 
  ...
  {:kanta_deep_l_plugin, "~> 0.1.1"}
end

# config/config.exs
config :kanta,
  ...
  plugins: [
    {Kanta.DeepL.Plugin, api_key: "YOUR_DEEPL_API_KEY"}
  ]

KantaSync

The KantaSync plugin allows you to synchronize translations between your production and staging/dev environments. It ensures that any changes made to translations in one are reflected in the others, helping you maintain consistency across different stages of development.

# mix.exs 
defp deps do 
  ...
  {:kanta_sync_plugin, "~> 0.1.0"}
end

You need to have Kanta API configured by using kanta_api macro.

# router.ex 
import KantaWeb.Router

scope "/" do 
  kanta_api("/kanta-api")
end

Authorization

Set KANTA_SECRET_TOKEN environment variable for restricting API access. It should be generated with mix phx.gen.secret 256 and both environments must have the same KANTA_SECRET_TOKEN environment variables.

You can also disable default authorization mechanism and use your own, by passing disable_api_authorization: true option into Kanta's config.

PO Writer

Kanta was created to allow easy management of static text translations in the application, however, for various reasons like wanting a backup or parallel use of other tools like TMS etc. you may want to overwrite .po files with translations entered in Kanta. To install it append {:kanta_po_writer_plugin, git: "https://github.com/curiosum-dev/kanta_po_writer_plugin"} to your deps list. Currently, it's not on Hex because it's in a pre-release version. Then add Kanta.Plugins.POWriter to the list of plugins, and new functions will appear in the Kanta UI to allow writing to .po files.

# mix.exs
defp deps
  ...
  {:kanta_po_writer_plugin, git: "https://github.com/curiosum-dev/kanta_po_writer_plugin"},
end

# config/config.exs
config :kanta,
  ...
  plugins: [
    Kanta.POWriter.Plugin
  ]

(back to top)

Roadmap

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. We prefer gitflow and Conventional commits style but we don't require that. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'feat: Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Curiosum

Michał Buszkiewicz - michal@curiosum.com

Krzysztof Janiec - krzysztof.janiec@curiosum.com

Artur Ziętkiewicz - artur.zietkiewicz@curiosum.com

(back to top)