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.
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.
- Elixir (tested on 1.14.0)
- Phoenix (tested on 1.7.0)
- Ecto SQL (tested on 3.6)
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.
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.
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
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
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
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
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.
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.
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.
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"}
]
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
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.
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
]
- 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).
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
Distributed under the MIT License. See LICENSE.txt
for more information.
Michał Buszkiewicz - michal@curiosum.com
Krzysztof Janiec - krzysztof.janiec@curiosum.com
Artur Ziętkiewicz - artur.zietkiewicz@curiosum.com