diff --git a/.gitignore b/.gitignore index bdd7ece..7876832 100644 --- a/.gitignore +++ b/.gitignore @@ -40,3 +40,4 @@ GEMINI.md .claude /.elixir_ls /.expert +/.lexical diff --git a/CHANGELOG.md b/CHANGELOG.md index 042108e..3547435 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,437 +1,213 @@ # Changelog All notable changes to this project will be documented in this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) -This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) - -## [v0.5.0] +## [0.5.0] ### Breaking Changes - **Gettext 1.0.0 Migration**: This version requires updating your Gettext module definition to use the new backend adapter system. You must define `use Kanta.Gettext.Backend` in your Gettext module and configure the adapter. ### Added -- Adds Gettext 1.0.0 compatibility with a custom backend adapter system -- Allow custom locales (ex. `es-es`) (#100) -- Stale messages detection nd merging (#120) +- Gettext versions v0.26 and v1.0.0 compatibility with via custom backend adapter system +- Allow custom locales (i.e. "`es-es`") (#100) +- Stale messages detection and merging (#120) - Updated Tailwind to v3.4.17 (#130) -## [v0.4.2] +## [0.4.2] - 2025-08-25 ### Fixed -- Fix Dialyzer errors related to Phoenix version detection (#122) +- Dialyzer errors related to Phoenix version detection (#122) - Replace Mix.Dep.Lock.read/0 with Application.spec/2 for better static analysis compatibility -- Add .dialyzer_ignore.exs to handle Phoenix dependency warnings +- .dialyzer_ignore.exs to handle Phoenix dependency warnings ### Added -- Add Phoenix 1.8 and Phoenix LiveView 1.x compatibility (#122) - -## [v0.4.1] -### Other -- feat: Expand Kanta.Query module (#86) -- Merge pull request #71 from kubosuke/feat/fix-pagination +- Phoenix 1.8 and Phoenix LiveView 1.x compatibility (#122) -Fix pagination logic for not showing many pages -- Merge pull request #85 from curiosum-dev/feature/command-to-invalidate-cache +Authored by: Jakub Lambrych +Signed-off-by: Michał Buszkiewicz -Command to invalidate cache -- feat: Add button for manual cache clearing -- Merge remote-tracking branch upstream/develop into feat/fix-pagination -- Merge pull request #84 from curiosum-dev/feature/improve-filter-bar-ui +## [0.4.1] - 2024-10-09 -Improve filter bar UI +### Added +- Expand Kanta.Query module (#86) +- Button for manual cache clearing (#85) +- Application source support +- Support for multiline msgids (#56) +- Support for nested scopes and different main path (#61) +- Support for different ID types (#52) +- Way to create new application source +- Way to clear all filters at once +- `dashboard_path` helper to verified routes +- `Colors` module +- Chevrons to `Icons` module +- Missing @moduledoc +- Versioce for version bumping +- Support for SQLite3 (#51) +- Doc to `compiling?` function +- Child LV dashboard components support (#42) +- Docs to DashboardLive + +### Changed +- Improve UX when editing many translations (#62) +- Improve filter bar UI (#84) - Make filters bar responsive -- Merge branch main into develop -- chore: :bookmark: Bump version to 0.4.0 (#82) -- Release/0.4.0 (#81) - -* Add application source - -* Add support for multiline msgids - -* Replace `parse_msgid/1` with just `Enum.join` - -* Changes to make import export plugin work - -* Fix translation preloads to preload only necessary data - -* Add support for nested scopes and different main path - -* Add a way to create new application source - -* Fix to `application_source_form_live` - -* Fixes to migrations - -* Add a way to clear all filters at once - -* Restore params after saving a translation - -* Add `dashboard_path` helper to verified routes - -* Improve readability of `Router` - -* Add `Colors` module - -* Add chevrons to `Icons` module - -* ❄️ Remove devenv - -* Fix credo - -* Remove autogenerated dummy test - -* Improve CI - -* Fix naming - -* Fix naming across file - -* Add supported Elixir versions - -* Remove unsupported OTP version - -* Set env - -* Use Ubuntu 24.04 LTS - -* Bump ecto versions - -* Bump uri_query version - -* Suppress warning about router.ex - -* Bump credo and dialyxir versions - -* Parse params and and redirects - -* Add support for different ID types - -* Return error when `id_parse_function` provided with MFA with invalid arity - -* Extract logic of `parse_filters/1`s reduce to `parse_filter/2` - -* Trigger workflow - -* Refactor translations_live.ex - -* Trigger workflow - -* Trigger workflow - -* Trigger workflow - -* Add missing @moduledoc - -* Fix - -* feat: :sparkles: add versioce for version bumping - -* chore: :bookmark: Bump version to 0.4.0 - ---------- - -Co-authored-by: Jakub Melkowski <9402720+Blatts12@users.noreply.github.com> -Co-authored-by: Maksymilian Jodłowski -Co-authored-by: Jan Świątek -- feat: :sparkles: add versioce for version bumping -- Merge pull request #62 from curiosum-dev/feature/ui-translation-improvements - -Improve UX when editing many translations -- Fix -- Merge branch develop into feature/ui-translation-improvements -- Merge pull request #59 from curiosum-dev/feature/add_support_for_multiple_apps - -Add support for multiple apps -- Add missing @moduledoc -- Merge branch develop into feature/add_support_for_multiple_apps -- Merge pull request #61 from curiosum-dev/feature/support-nested-scopes - -Add support for nested scopes and different main path -- Merge branch develop into feature/support-nested-scopes -- Trigger workflow -- Merge pull request #60 from curiosum-dev/fix/multiple-locales-for-messages-fixes - -Fix translation preloads to preload only necessary data -- Merge branch develop into fix/multiple-locales-for-messages-fixes -- Trigger workflow -- Merge pull request #56 from curiosum-dev/fix/multiline-translations - -Add support for multi-line msgids -- Merge branch develop into fix/multiline-translations -- Trigger workflow -- Merge pull request #52 from curiosum-dev/fix/parse_params_to_avoid_500s - -Parse params and add support for different ID types +- Improve readability of `Router` +- Improve CI (#80) +- Improve UX when using filters (#49) +- Improve efficiency of messages list query - Refactor translations_live.ex -- Trigger workflow +- Update pagination.ex +- Replace `parse_msgid/1` with just `Enum.join` - Extract logic of `parse_filters/1`s reduce to `parse_filter/2` -- Return error when `id_parse_function` provided with MFA with invalid arity -- Add support for different ID types -- Parse params and and redirects -- Merge pull request #80 from curiosum-dev/feature/improve-ci +- Support for newer phoenix_html 4 with phoenix_html_helpers (#47) +- Support translations during compilation (#48) +- Search for PO files only in priv/gettext (#41) +- PO Extractor - allow to import multi-lines msgstr (#40) -Feature/improve ci -- Bump credo and dialyxir versions -- Suppress warning about router.ex -- Bump uri_query version +### Fixed +- Pagination logic for not showing many pages (#71) +- Translation preloads to preload only necessary data (#60) +- `application_source_form_live` +- Migrations +- Pagination failing to parse int (#44) +- Credo issues +- Naming across file + +### Changed (Dependencies) - Bump ecto versions -- Use Ubuntu 24.04 LTS -- Set env -- Remove unsupported OTP version +- Bump uri_query version +- Bump credo and dialyxir versions +- Use Ubuntu 24.04 LTS in CI - Add supported Elixir versions -- Fix naming across file -- Fix naming -- Improve CI -- Merge pull request #77 from curiosum-dev/feat/remove-devenv - -❄️ Remove devenv -- Merge pull request #79 from curiosum-dev/fix/align-with-main +- Remove unsupported OTP version -Fix/align with main -- Remove autogenerated dummy test -- Fix credo -- ❄️ Remove devenv -- Add chevrons to `Icons` module -- Add `Colors` module -- Improve readability of `Router` -- Add `dashboard_path` helper to verified routes -- Update pagination.ex +### Changed (Configuration) - Restore params after saving a translation -- Add a way to clear all filters at once -- Fixes to migrations -- Fix to `application_source_form_live` -- Add a way to create new application source -- Add support for nested scopes and different main path -- Fix translation preloads to preload only necessary data -- Changes to make import export plugin work -- Replace `parse_msgid/1` with just `Enum.join` -- Add support for multiline msgids -- Add application source -- Add support for SQLite3 (#51) - -* Add support for SQLite3 - -* Fix current version - Recover filters from params on mount in the translations list (#49) +- Properly find index in Select +- Parse params and add redirects +- Return error when `id_parse_function` provided with MFA with invalid arity +- Suppress warning about router.ex +- Changes to make import export plugin work -* Improve UX when using filters - -* Properly find index in Select -- 🐛 Fix pagination failing to parse int (#44) -- Support translations during compilation (#48) - -* Support translations during compilation - -* Remove Logger - -* Fix credo issues - -* Add doc to `compiling?` function -- Support for newer phoenix_html 4 with phoenix_html_helpers because newer version has a little different api (#47) - -* html_helpers - -Signed-off-by: Jan Jakůbek - -* delete_use_PhoenixHtml - -Signed-off-by: Jan Jakůbek +### Removed +- Remove devenv (#77) +- Remove autogenerated dummy test +- Remove Logger ---------- +Co-authored-by: Jakub Melkowski <9402720+Blatts12@users.noreply.github.com> +Co-authored-by: Maksymilian Jodłowski +Co-authored-by: Jan Świątek Signed-off-by: Jan Jakůbek -- Merge pull request #42 from curiosum-dev/feature/child-lv-components - -Dashboard allow child live view components -- 📝 Add docs to DashboardLive -- 💫 Support child LV dashboard components -- Merge pull request #41 from curiosum-dev/feature/stricter-po-file-search - -🚦 Search for PO files only in priv/gettext -- Merge pull request #40 from oliver-kriska/feature/multi-line-msgstr -PO Extractor - allow to import multi-lines msgstr -- 🚦 Search for PO files only in priv/gettext -- Update README.md -- PO Extractor - allow to import multi-lines msgstr -- Merge pull request #38 from curiosum-dev/chore/kanta-sync-readme-plugins-list-update +## [0.3.1] - 2023-10-13 -Update README.md -- Update README.md - -Adds Kanta sync to the plugins list in README Table of contents - -## [0.3.1] -### Other -- Merge pull request #37 from curiosum-dev/release/0.3.1 - -Release/0.3.1 -- Merge branch main into release/0.3.1 -- Merge pull request #36 from curiosum-dev/feature/api-endpoint +### Added +- API endpoints (#36) +- Optional API authorization +- @moduledoc to APIAuthPlug +- API scaffolding -Feature/api endpoint -- Add optional API authorization, resolve minor naming issues -- Add @moduledoc to APIAuthPlug -- Add API endpoints -- Merge branch develop into feature/api-endpoint -- Create API scaffolding +### Fixed +- Minor naming issues -## [0.3.0] -### Other -- Merge pull request #35 from curiosum-dev/release/0.3.0 +## [0.3.0] - 2023-09-26 -Release/0.3.0 +### Changed - Update phoenix_live_view to 0.20 - Update Kanta version to 0.3.0 -- Merge pull request #34 from curiosum-dev/fix/js-error-on-liveview-page-change +- Improve translations search (#21) +- Improve efficiency of messages list query +- Require opts keyword list in join_resource/3 -Fix JS error on LiveView page change +### Fixed +- JS error on LiveView page change (#34) +- README missing import in router (#32) + +### Deprecated - Get rid of deprecated live_component/2 -- Fix JS error on LiveView page change -- Merge pull request #32 from FranciscoLira/fix/router-import-missing -Fix/router import missing -- Merge pull request #21 from curiosum-dev/feature/improved-translations-search +## [0.2.2] - 2023-09-05 -Improve translations search -- Require opts keyword list in join_resource/3 -- Improve efficiency of messages list query -- Merge branch develop into feature/improved-translations-search -- fix:README missing import in router -- Improve translations search +### Changed +- Update information about POWriter (#29) +- Add badges (#27) -## [0.2.2] -### Other -- Merge pull request #30 from curiosum-dev/release/0.2.2 +## [0.2.1] - 2023-09-04 -Release/0.2.2 -- Merge branch main into release/0.2.2 -- Merge pull request #29 from curiosum-dev/chore/update-powriter-information-in-readme +### Changed +- Add badges (#28) +- Update README to match Kanta version (#26) -Update information about POWriter -- Update information about POWriter -- Merge pull request #27 from curiosum-dev/feature/readme-and-sidebar-badges +## [0.2.0] - 2023-09-04 -Add badges -- Add badges +### Added +- Dialyzer (#18) +- Plugin docs, specs and conditional components rendering (#18) -## [0.2.1] -### Other -- Add badges (#28) -- Merge pull request #26 from curiosum-dev/chore/update-readme +### Changed +- Set docs entry and bump mix version (#24) +- Update "How to write plugins?" tutorial (#18) +- Update gettext repo (#22) +- Update demo link in README (#20) +- Module names consistency, explicit ArgumentError rescue (#18) -Update README to match Kanta version -- Update README to match Kanta version +### Fixed +- Improve UI and plural translations form (#23) +- Use truncate CSS prop instead of String.slice +- Credo and dialyzer warnings (#18) +- Wrong type (it was a Map all along) +- Multitenancy projects issues (#14) +- Down migration order (#14) +- prefix() calls into prefix (#14) +- Phoenix VerifiedRoutes issues & missing views (#10) +- Kanta in mix release projects (#8) + +### Changed +- Fallback to public prefix for messages (#14) +- Pass on_mount option to live_session opts (#14) +- Use https instead ssh connection for gettext (#14) +- Pass down opts to respective up&down migrations (#14) +- Add limit 1 (#14) +- Rework plural messages handling (#14) +- Change unverified url to unverified path (#11) +- Extract DeepL plugin to external package (#12) -## [0.2.0] -### Other -- Merge pull request #25 from curiosum-dev/release/0.2.0 +### Added +- Devenv (#14) -Release/0.2.0 -- Merge pull request #24 from curiosum-dev/feature/set-docs-entry-and-bump-mix-version +## [0.1.0] - 2023-05-18 -Set docs entry and bump mix version -- Set docs entry and bump mix version -- Merge pull request #23 from curiosum-dev/fix/plural-translations-form +Initial version of Kanta translations manager. -Improve UI and fix plural translations form -- Use truncate CSS prop instead of String.slice -- Improve UI and plural translations form -- Merge pull request #22 from curiosum-dev/chore/update-gettext-repo - -Update gettext repo -- Update gettext repo -- Merge pull request #20 from curiosum-dev/chore/update-demo-link - -Update demo link in README -- Update demo link in README -- Merge pull request #18 from curiosum-dev/feature/plugin-docs - -Feature/plugin docs -- Module names consistency, explicit ArgumentError rescue -- Add dialyzer, fix credo and dialyzer warnings -- Update "How to write plugins?" tutorial -- Plugin docs, specs and conditional components rendering -- 🐛 Hotfix wrong type - -It was a Map all along -- Merge pull request #14 from curiosum-dev/bugfix/prerelease-fixes - -Bugfix/prerelease fixes -- 🔧 Fallback to public prefix for messages -- 🔧 Pass on_mount option to live_session opts -- 🐛 Use https instead ssh connection for gettext -- 🐛 Fix down migration order -- 🐛 Fix prefix() calls into prefix -- 🔧 Pass down opts to respective up&down migrations -- 🐛 Add limit 1 -- ❄ Add devenv -- fix: multitenancy projects issues -- feat: rework plural messages handling -- Merge pull request #12 from curiosum-dev/feature/kanta-plugins-extraction - -feat: extract DeepL plugin to the external package -- feat: extract DeepL plugin to the external package -- Merge pull request #11 from curiosum-dev/fix/phoenix-verified-url - -fix: change unverified url to unverified path -- fix: change unverified url to unverified path -- Merge pull request #10 from curiosum-dev/fix/phoenix-verified-paths - -fix: Phoenix VerifiedRoutes issues & missing views -- fix: Phoenix VerifiedRoutes issues & missing views -- Merge pull request #8 from curiosum-dev/fix/kanta-in-mix-release-setup - -fix: Kanta in a mix release projects -- fix: Kanta in a mix release projects -- Merge tag 0.1.0 into develop - -Initial version of Kanta - -## [0.1.0] -### Other -- Merge branch release/0.1.0 into main -- chore: bump version -- docs: update readme -- feat: basic rwd -- feat: dark mode -- feat: add messages filters -- feat: plugins management -- feat: small refactoring -- fix: paths resolution -- feat: add gettext contexts & fix plural translations -- feat: mainly UI adjusts -- Merge pull request #6 from curiosum-dev/1-fix_github_dependency_on_gettext_fork - -Fix github dependency on gettext fork (#1) -- Fix github dependency on gettext fork (#1) -- Merge tag 0.0.1-rc1 into develop - -First release candidate of Kanta translations manager. -- Merge branch release/0.0.1-rc1 -- chore: update package version -- Merge pull request #4 from curiosum-dev/feature/KNT-2 - -fix: cached translations in UI -- fix: cached translations in UI -- Merge pull request #3 from curiosum-dev/feature/KNT-1 - -KNT-1 mimic LiveDashboard mechanism in Kanta -- fix: LV redirect loop -- feat: reverse engineering of live dashboard (WIP) -- feat: adjust gettext repo for plural messages handling -- feat: add form for plural translation updates -- feat: add form for singular translation updates -- Merge pull request #1 from curiosum-dev/feature/petal_init - -PETAL stack init & db structure rework -- feat: rework translation listings -- feat: add plural translations -- feat: add nebulex as a caching tool -- feat: add sample pages in petal -- feat: add basic configuration for semi-PETAL stack -- chore: update deps & readme +### Added +- Basic rwd (responsive web design) +- Dark mode +- Messages filters +- Plugins management +- Gettext contexts +- Form for plural translation updates +- Form for singular translation updates +- Plural translations +- Nebulex as a caching tool +- Sample pages in petal +- Basic configuration for semi-PETAL stack +- PopulateCacheWithStoredDataService +- File structure + +### Changed +- Update readme +- Update package version +- Update deps & readme +- Rework translation listings - Change translations to singular translations -- Create PopulateCacheWithStoredDataService -- Proof of concept -- Create file structure -- First commit +- Mimic LiveDashboard mechanism in Kanta (#3) +- Adjust gettext repo for plural messages handling +- Mainly UI adjusts +- Small refactoring + +### Fixed +- Github dependency on gettext fork (#6, #1) +- Plural translations +- Cached translations in UI (#4) +- LV redirect loop +- Paths resolution diff --git a/README.md b/README.md index f470105..4b59a8f 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,30 @@ +# Kanta Guide

Kanta

User-friendly translations manager for Elixir/Phoenix projects

- [![Contact Us](https://img.shields.io/badge/Contact%20Us-%23F36D2E?style=for-the-badge&logo=maildotru&logoColor=white&labelColor=F36D2E)](https://curiosum.com/contact) - [![Visit Curiosum](https://img.shields.io/badge/Visit%20Curiosum-%236819E6?style=for-the-badge&logo=elixir&logoColor=white&labelColor=6819E6)](https://curiosum.com/services/elixir-software-development) - [![License: MIT](https://img.shields.io/badge/License-MIT-1D0642?style=for-the-badge&logo=open-source-initiative&logoColor=white&labelColor=1D0642)](https://github.com/curiosum-dev/kanta/blob/main/LICENSE.md) +

+ + Contact Us + + + Visit Curiosum + + + License: MIT + +


-# About The Project - +## About The Project
- Logo + Logo

@@ -45,7 +53,7 @@ If you're working on an Elixir/Phoenix project and need to manage translations,
-# Table of contents +## Table of contents
  • @@ -68,6 +76,7 @@ If you're working on an Elixir/Phoenix project and need to manage translations,
    • @@ -104,16 +113,16 @@ _Note: Official documentation for Kanta library is [available on hexdocs][hexdoc

    (back to top)

    -# Getting Started +## Getting Started -## Prerequisites +### Prerequisites -- Elixir (tested on 1.18.4) +- Elixir (tested on 1.19.0) - Phoenix (tested on 1.7.x and 1.8.x with LiveView 1.x) - Ecto SQL (tested on 3.13) - PostgreSQL 15+ or SQLite 3.31.0+ -## Installation +### Installation The package can be installed by adding `kanta` to your list of dependencies in `mix.exs`: @@ -121,12 +130,12 @@ by adding `kanta` to your list of dependencies in `mix.exs`: ```elixir def deps do [ - {:kanta, "~> 0.4.2"}, + {:kanta, "~> 0.5.0"}, ] end ``` -## Configuration +### Configuration Add to `config/config.exs` file: @@ -141,7 +150,7 @@ config :my_app, Kanta, 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 +### 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: @@ -152,12 +161,12 @@ mix ecto.gen.migration add_kanta_translations_table Open the generated migration file and set up `up` and `down` functions. **Current Migration Versions:** -- PostgreSQL: **v4** (adds default context support for Gettext 0.26 backend) -- SQLite: **v3** (adds default context support for Gettext 0.26 backend) +- PostgreSQL: **v4** (adds default context support for Gettext >= `0.26` backend) +- SQLite: **v3** (adds default context support for Gettext >= `0.26` backend) If you're upgrading from an earlier version of Kanta, update your migration version to the latest. -### PostgreSQL +#### PostgreSQL ```elixir defmodule MyApp.Repo.Migrations.AddKantaTranslationsTable do @@ -174,7 +183,7 @@ defmodule MyApp.Repo.Migrations.AddKantaTranslationsTable do end ``` -### SQLite +#### SQLite ```elixir defmodule MyApp.Repo.Migrations.AddKantaTranslationsTable do @@ -197,25 +206,35 @@ After that run: mix ecto.migrate ``` -## Gettext module - -Configuring Gettext requires just a single change. +### Gettext module -Wherever you have: +Configuring Gettext requires just a single change to use `Kanta.Backend`: ```elixir -use Gettext, backend: YourApp.Gettext +defmodule MyAppWeb.Gettext do + use Kanta.Backend, otp_app: :my_app +end ``` -replace it with: +If you're using a Gettext version < `0.26`, refer to the [official documentation](https://github.com/elixir-gettext/gettext) for migration instructions. + +### Using Gettext in the application + +Using gettext across the app does not differ from the regular `Gettext` usage: ```elixir -use Kanta.Gettext, backend: YourApp.Gettext -``` +defmodule MyAppWeb.CustomComponent do + use Gettext, backend: MyAppWeb.Gettext -If you're using a Gettext version lower than 0.26, refer to the [official documentation](https://github.com/elixir-gettext/gettext) for migration instructions. + def render(assigns) do + ~H""" + {gettext("Actions")} + """ + end +end +``` -## Kanta Supervisor +### Kanta Supervisor In the `application.ex` file of our project, we add Kanta and its configuration to the list of processes. @@ -230,7 +249,7 @@ In the `application.ex` file of our project, we add Kanta and its configuration end ``` -## Kanta UI +### Kanta UI Inside your `router.ex` file we need to connect the Kanta panel using the kanta_dashboard macro. @@ -246,37 +265,52 @@ end

    (back to top)

    -# Features +## Features -## Extracting from PO files +### Extracting from PO files -messages +![Messages](assets/images/readme/messages.png) 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 +### Storing messages in the database + -singular +![Singular translation edit](assets/images/readme/singular.png) 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. -With Gettext 0.26+, Kanta uses a custom backend adapter system (`Kanta.Backend.Adapter.CachedDB`) that fetches translations from the database/cache at runtime instead of compiled PO files. 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. +With Gettext version >= `0.26`, Kanta uses a custom backend adapter system (`Kanta.Backend.Adapter.CachedDB`) that fetches translations from the database/cache at runtime instead of compiled PO files. 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. + +### Detection of stale messages + +![Stale Dashboard Tiles](assets/images/readme/stale-dashboard.png) + +Kanta automatically detects **stale** messages and will help you out with managing them - either `deleting` or `merging` into existing ones. + +`Stale messages` are the translations that exist in your database but are no longer present in any locale's PO files. This typically happens during code refactoring when translation keys in the codebase are removed or renamed. + +Using fuzzy matching, Kanta identifies stale but **"mergeable"** messages where stale translations closely resemble active messages. + +![Stale messages in Locales view](assets/images/readme/stale-one-by-one.png) + +You can take action one by one for every message (delete and/or merge) or you can perform it in bulk (from the Dashboard). -## Translation progress +### Translation progress -dashboard +![Translation progress](assets/images/readme/dashboard.png) 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 +## Plugins -## DeepL +### 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. -plural +![Plural](assets/images/readme/plural.png) ```elixir # mix.exs @@ -295,7 +329,7 @@ config :kanta, ] ``` -## KantaSync +### KantaSync The [KantaSync plugin](https://github.com/curiosum-dev/kanta_sync_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. @@ -318,13 +352,13 @@ scope "/" do end ``` -### Authorization +#### 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 +### 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. @@ -347,7 +381,7 @@ config :kanta,

    (back to top)

    -## Roadmap +### Roadmap - [ ] Typespecs, tests, better docs - [ ] CI/CD @@ -361,17 +395,17 @@ See the [open issues](https://github.com/curiosum-dev/kanta/issues) for a full l

    (back to top)

    -# Development +## Development -## Running Tests +### Running Tests If you're contributing to Kanta development, you'll need to run the test suite. The tests require a PostgreSQL database. -### Prerequisites for Development +#### Prerequisites for Development - PostgreSQL 15+ (for running tests) - All prerequisites listed in [Getting Started](#prerequisites) -### Test Setup +#### Test Setup First-time setup (or if tests are failing due to database issues): @@ -382,7 +416,7 @@ MIX_ENV=test mix ecto.drop && MIX_ENV=test mix ecto.create && MIX_ENV=test mix e -## Contributing +### 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**. @@ -399,14 +433,14 @@ Don't forget to give the project a star! Thanks again! -## Community +### Community - **Slack channel**: [Elixir Slack / #kanta](https://elixir-lang.slack.com/archives/C099BMEN5BP) - **Issues**: [GitHub Issues](https://github.com/curiosum-dev/kanta/issues) - **Discussions**: [GitHub Discussions](https://github.com/curiosum-dev/kanta/discussions) - **Blog**: [Curiosum Blog](https://curiosum.com/blog?search=kanta) -## License +### License Distributed under the MIT License. See `LICENSE.txt` for more information. @@ -414,7 +448,7 @@ Distributed under the MIT License. See `LICENSE.txt` for more information. -## Contact +### Contact [Curiosum](https://curiosum.com) diff --git a/dashboard.png b/assets/images/readme/dashboard.png similarity index 100% rename from dashboard.png rename to assets/images/readme/dashboard.png diff --git a/locales.png b/assets/images/readme/locales.png similarity index 100% rename from locales.png rename to assets/images/readme/locales.png diff --git a/assets/images/readme/logo.png b/assets/images/readme/logo.png new file mode 100644 index 0000000..a0d6922 Binary files /dev/null and b/assets/images/readme/logo.png differ diff --git a/messages.png b/assets/images/readme/messages.png similarity index 100% rename from messages.png rename to assets/images/readme/messages.png diff --git a/plural.png b/assets/images/readme/plural.png similarity index 100% rename from plural.png rename to assets/images/readme/plural.png diff --git a/singular.png b/assets/images/readme/singular.png similarity index 100% rename from singular.png rename to assets/images/readme/singular.png diff --git a/assets/images/readme/stale-dashboard.png b/assets/images/readme/stale-dashboard.png new file mode 100644 index 0000000..0661b51 Binary files /dev/null and b/assets/images/readme/stale-dashboard.png differ diff --git a/assets/images/readme/stale-one-by-one.png b/assets/images/readme/stale-one-by-one.png new file mode 100644 index 0000000..acf9f3a Binary files /dev/null and b/assets/images/readme/stale-one-by-one.png differ diff --git a/mix.exs b/mix.exs index d516ad2..5ce4806 100644 --- a/mix.exs +++ b/mix.exs @@ -16,11 +16,7 @@ defmodule Kanta.MixProject do aliases: aliases(), deps: deps(), dialyzer: dialyzer(), - docs: [ - extras: ["docs/how-to-write-plugins.md"], - assets: "docs/assets", - main: "Kanta" - ] + docs: docs() ] end @@ -90,4 +86,16 @@ defmodule Kanta.MixProject do ignore_warnings: ".dialyzer_ignore.exs" ] end + + defp docs do + [ + extras: ["README.md", "docs/how-to-write-plugins.md", "CHANGELOG.md"], + groups_for_extras: [ + "Kanta Guide": ~r/README|how-to-write-plugins/ + ], + assets: %{"docs/assets" => "assets", "assets/images/readme" => "assets/images/readme"}, + main: "readme", + logo: "logo.png" + ] + end end