git as single source of truth

[samuelstroschein]

Will be implemented. See #127

Introduction

A major issue of inlang is synchronizing translation files and corresponding merges as described in https://github.com/inlang/inlang/discussions/101. The latter is impossible without version history.

The idea

The inlang dashboard is a UI for non-technical people to manage translations powered by git under the hood.

Git solves many of the problems that this discussion is about: version control, sync, branching, and whatnot. Inlangs implementation offers the possibility to go "stateless". The dashboard could act as UI for translation files hosted in a git repository. Changes that translators conduct are not saved in the dashboard, or a dedicated file in the database, but instead directly committed to the repo.

Pros

• no need to sync and merge
• branching essentially for free
• version control essentially for free
• use the inlang dashboard without an account/setting up a project
  Communities can do the translations for FOSS projects with an intuitive UI instead of manually editing JSON files etc. See issues like cibernox/svelte-intl-precompile#33
• no data duplication
  The developer tools require a config. So does the dashboard. Both configs are, due to the nature of the architecture, separated. The one is in the source code, the other one is stored in the database.

Neutral

• why should translations live in source code?
  It's not the job of developers to manage translations.

Cons

• commits can convolute the git history of the source code repository
  • some teams have separate git repos just for translations
  • got be diminished by squash merging.
• localization consists of much more than what inlang currently offers.
  Additional features/requirements/problems that occur down the road are likely better off in a standard relational schema.

[ivanhofer]

At work we currently use something similar. But instead of the translation service writing into our git repository, we fetch new translations from teh API the service provides.

In a nutshell our workflow looks like this:

1. a developer implements the design from a figma file
2. when some text is involved, he comes up with a meaningful key and writes the text only into the dictionary file of the base translation ('en')
3. once the PR get's merged int the main branch, an GH Action looks for new entries in the dictionary and pushes the translations to the service
4. translators get notified about the new entries and can make their adjustments
5. (currently) once per day an automatic GH Action fetches all dictionaries from the translation service and creates a new PR if changes were found. For now we check the entries manually but we plan to auto-merge those PRs if all checks are passing.

The approach above has those benefits:

• the developer doesn't need to bother with the translation service. He only works within the IDE and doesn't care about other languages when he implements a new feature (except for locale specific formatting options)
• translations arrive whenever they are ready. We can use english as a fallback if e.g. the italian translator is on vacation but the new feature should be pushed immediately to production. Once the feature is setup for the base translation, no developer is needed to be involved
• the CI pipeline runs and checks with the help of typesafe-i18n if the translations are valid (at least from a technical perspective)
• because it is integrated into the git workflow, we can use e.g. branch deployments to test the new translations before they go into production

Possible improvements:

• instead of fetching dictionaries once per day, we could let us notify via a webhook if something has changed (not sure if the service supports this)
• (planned) provide a way for the translators to test the changes immediately on the production system (via a flag or something similar)

@samuelstroschein I think using git as the underlaying source of truth makes sense. At least it would work how I usually develop my projects.

Some possible shortcomings you should consider:

• the project probably needs a CI pipeline in order for translations to show up in the production system
• some companies with strict security guidelines may ask: do I trust inlang to not sell my other code I have in this repo

But the problems above could be easily solved if inlang could either

• hook into an existing repo, where all the source code lives
• or can be used in a git repository that only holds translations and the actual source code lives somewhere else. This would mean that inlang needs to provide an API to fetch the translation data in a meaningful way.
  In order for non-technical people to setup a repository, maybe inlang should provide a "click here to get started" way, and create a new
  private repository inside the inlang account.

Hope my thoughts help you :)

[samuelstroschein]

As always Ivan, your input is highly appreciated!