franciscolira / kanta

User-friendly translations manager for Elixir/Phoenix projects.

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

• About The Project
• Getting Started
  • Prerequisites
  • Installation
  • Configuration
  • Database Migrations
  • Gettext Module
  • Kanta Supervisor
  • Kanta UI
• Features
  • Extracting from PO files
  • Storing messages in the database
  • Translation progress
• Plugins
  • PO Writer
  • DeepL
• 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.2.2"},
    {:gettext, git: "[email protected]: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: 1, prefix: prefix()) # Prefix is needed if you are using multitenancy with i.e. triplex
  end

  def down do
    Kanta.Migration.down(version: 1, 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.

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
  ...
  {:kanta_deep_l_plugin, "~> 0.1.1"}
end

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

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

• Typespecs, tests, better docs
• CI/CD
• Gettext extract/merge automation
• Google Translate, Yandex Translate, LibreTranslate Plugins
• File import/export
• Bumblebee AI translations
• REST API

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!

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

(back to top)

License

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

(back to top)

Contact

Michał Buszkiewicz - [email protected]

Krzysztof Janiec - [email protected]

Artur Ziętkiewicz - [email protected]

(back to top)