Proposal: move options/locale to a git submodule #3919

New Issue

GiteaMirror · 2025-11-02T05:30:34-06:00

GiteaMirror commented

2025-11-02 05:30:34 -06:00

Originally created by @guillep2k on GitHub (Sep 9, 2019).

Based on some discussion that happened on discord, I'd like to propose moving options/locale to a git submodule.

The following is a general presentation of the proposal; many details were left out for the sake of clarity.

Motivations

1. Currently translations lag one major version behind.

Translations are crowd-sourced, so in most cases users will add translations only after a release is out, or more specifically, when they upgrade.

When Gitea 1.11.0 is released, a number of new features will come with it. Most of them will only be available in English, as users from other languages may not be aware of the new strings until after they install the version. They may now go to Crowding and help with translations, but now they must wait until 1.12.0 to see their work distributed, as do all people using that language.

Furthermore, they can go to Crowdin to add something they see untranslated in their copy, only to see that the translation is already there, giving them a mixed impression about the translation support in Gitea.

2. Updated translations require upgrading Gitea or a manual procedure to download the latest version.

Some official way of updating the translations after the version is out would be desirable. Currently users need to clone the entire Gitea repository to get the latest translations.

3. Maintaining local translations in sync with official is difficult and error-prone.

Many times translations for a language are perfect, but there are local variants that could use some improvement. Spanish (my native language), for example, has 480 million native speakers world-wide, but most of them are not from Spain. There are at least three major dialects of Spanish (Spain, Latin-America, Rio de la Plata). Surely, the locale system supports local variations (es-ES vs. es-AR), but sometimes it's better to leave most of the file untouched and modify some resources.

Due to the ever-evolving nature of computing terms, some cultures tend to maintain the English term for some specific actions. For example, "commit" has an every-day meaning in English, but here in Argentina "commit" is used unstranslated having only the computer-related meanings. I'm sure that many cultures go through this, and some are more prone to use the local translation while some will use the English word, even if those cultures speak the same language. For instance, I find Spain to be more prone to use a Spanish term rather than the original English one.

So, there is potential for allowing micro-translations that every user may want to handle in their server.

The proposal

So, one way of addressing all these issues is to make options/locale a git submodule. Unlike Go or Crowdin, git is the common denominator for both developers and users of Gitea. Everybody knows how to use a git repository, and Gitea is great for that!

On Crowdin and the main repository

First, there must be a new repository (e.g. gitea.com/gitea/gitea-locale) owned by Gitea; Crowdin must commit to that, instead of to the current go-gitea/gitea.

Then in go-gitea/gitea there must be a submodule pointing to that repository:

cd code.gitea.io/gitea/options
git submodule add https://gitea.com/gitea/gitea-locale locale

Every time Crowdin commits to local, a hook in gitea-locale should also trigger the following in a local copy of go-gitea/gitea:

git submodule update
git commit ...
git push

On the Gitea installation

Now users can install Gitea as they are used to, no (fundamental) changes there. They can build and run Gitea, or use a docker image, whatever.

On installation, Gitea would clone gitea.com/gitea/gitea-locale locally and create a branch named local from that. Macaron would use that folder to pick up the translatable resources.

Now we can use the repository administration capabilities in Gitea to let the user manage their local clone of gitea/gitea-locale, like:

Pull changes from origin/master (i.e. Gitea's own server) and merge them in their local branch.
Pull changes from another source.
Make local changes that be can easily maintained, as Gitea (git) will respect their latest version over the original, line by line.
Cherry-pick entire languages without affecting other locales (well... not yet from Gitea, but with git).

Immediate benefits

Users will have an easy way of updating their translations (e.g. an option in /admin Maintenance Operations), so they will always be up-to-date with them.
Users will have more control over the way their translations are managed.
Users can handle specific lines in their translation without losing sync with Gitea's constant evolution.
Most of the code is already there.
Even if no changes are implemented in Gitea's code (e.g. menu options to handle the translations clone localy), just by using a clone the users can have most of the benefits from command line.

Future

In the future there could be some kind of plugin for the user to push all of their local changes to Crowdin, so they can help with their work while seeing immediate benefits in their copy.

Needs polishing?

Yes, of course. For example, there should be an easy way to deal with the English translation for developers to work with. Many solutions come to mind, but first let's see if the general idea has some consensus.

Other points to consider are:

How the different CI scripts need to be updated.
Any other concerns you may have.

Originally created by @guillep2k on GitHub (Sep 9, 2019). Based on [some discussion that happened on discord](https://discordapp.com/channels/322538954119184384/322538954119184384/619529239708041227), I'd like to propose moving `options/locale` to a [git submodule](https://git-scm.com/docs/git-submodule). The following is a general presentation of the proposal; many details were left out for the sake of clarity. ## Motivations ### 1. Currently translations lag one major version behind. Translations are crowd-sourced, so in most cases users will add translations only after a release is out, or more specifically, when they _upgrade_. When Gitea 1.11.0 is released, a number of new features will come with it. Most of them will only be available in English, as users from other languages may not be aware of the new strings until after they install the version. They may now go to Crowding and help with translations, but now they must wait until 1.12.0 to see their work distributed, as do all people using that language. Furthermore, they can go to Crowdin to add something they see untranslated in their copy, only to see that the translation is already there, giving them a mixed impression about the translation support in Gitea. ### 2. Updated translations require upgrading Gitea or a manual procedure to download the latest version. Some _official_ way of updating the translations after the version is out would be desirable. Currently users need to clone the entire Gitea repository to get the latest translations. ### 3. Maintaining local translations in sync with official is difficult and error-prone. Many times translations for a language are perfect, but there are local variants that could use some improvement. Spanish (my native language), for example, has 480 million native speakers world-wide, but most of them are not from Spain. There are at least three major dialects of Spanish (Spain, Latin-America, Rio de la Plata). Surely, the locale system supports local variations (es-ES vs. es-AR), but sometimes it's better to leave most of the file untouched and modify _some_ resources. Due to the ever-evolving nature of computing terms, some cultures tend to maintain the English term for some specific actions. For example, "commit" has an every-day meaning in English, but here in Argentina "commit" is used unstranslated having only the computer-related meanings. I'm sure that many cultures go through this, and some are more prone to use the local translation while some will use the English word, **even if those cultures speak the same language**. For instance, I find Spain to be more prone to use a Spanish term rather than the original English one. So, there is potential for allowing micro-translations that every user may want to handle in their server. ## The proposal So, one way of addressing all these issues is to make `options/locale` a git submodule. Unlike Go or Crowdin, git is the common denominator for both developers and users of Gitea. Everybody knows how to use a git repository, and Gitea is great for that! ### On Crowdin and the main repository First, there must be a new repository (e.g. `gitea.com/gitea/gitea-locale`) owned by Gitea; Crowdin must commit to that, instead of to the current `go-gitea/gitea`. Then in `go-gitea/gitea` there must be a submodule pointing to that repository: ``` cd code.gitea.io/gitea/options git submodule add https://gitea.com/gitea/gitea-locale locale ``` Every time Crowdin commits to `local`, a hook in `gitea-locale` should also trigger the following in a local copy of `go-gitea/gitea`: ``` git submodule update git commit ... git push ``` ### On the Gitea installation Now users can install Gitea as they are used to, no (fundamental) changes there. They can build and run Gitea, or use a docker image, whatever. On installation, Gitea would clone `gitea.com/gitea/gitea-locale` locally and create a branch named `local` from that. Macaron would use that folder to pick up the translatable resources. Now we can use the repository administration capabilities in Gitea to let the user manage their local clone of `gitea/gitea-locale`, like: * Pull changes from `origin/master` (i.e. Gitea's own server) and merge them in their `local` branch. * Pull changes from another source. * Make local changes that be can easily maintained, as Gitea (git) will respect their latest version over the original, **line by line**. * Cherry-pick entire languages without affecting other locales (well... not yet from Gitea, but with git). ## Immediate benefits * Users will have an easy way of updating their translations (e.g. an option in `/admin` Maintenance Operations), so they will always be up-to-date with them. * Users will have more control over the way their translations are managed. * Users can handle specific lines in their translation without losing sync with Gitea's constant evolution. * Most of the code is already there. * Even if no changes are implemented in Gitea's code (e.g. menu options to handle the translations clone localy), just by using a clone the users can have most of the benefits from command line. ## Future In the future there could be some kind of plugin for the user to push all of their local changes to Crowdin, so they can help with their work while seeing immediate benefits in their copy. ## Needs polishing? Yes, of course. For example, there should be an easy way to deal with the English translation for developers to work with. Many solutions come to mind, but first let's see if the general idea has some consensus. Other points to consider are: * How the different CI scripts need to be updated. * Any other concerns you may have.

GiteaMirror added the type/proposal label 2025-11-02 05:30:34 -06:00

GiteaMirror closed this issue

2025-11-02 05:30:35 -06:00

GiteaMirror commented

2025-11-02 05:30:35 -06:00

@lunny commented on GitHub (Sep 9, 2019):

Maybe we could create one repository for every gitea version when release branch created via crowdin's API. Then even gitea moved a new version, translators still could change the older version translation and update it. And if then I think gitea could download translations and merge them to the correct gitea release branch.

Users already could put their translations on custom/options/locale to replace default translations.

@lunny commented on GitHub (Sep 9, 2019): Maybe we could create one repository for every gitea version when release branch created via crowdin's API. Then even gitea moved a new version, translators still could change the older version translation and update it. And if then I think gitea could download translations and merge them to the correct gitea release branch. Users already could put their translations on `custom/options/locale` to replace default translations.

GiteaMirror commented

2025-11-02 05:30:36 -06:00

@lunny commented on GitHub (Sep 9, 2019):

And a new repositories' translations will be copied from the older version so that most translations will have been done.

@lunny commented on GitHub (Sep 9, 2019): And a new repositories' translations will be copied from the older version so that most translations will have been done.

GiteaMirror commented

2025-11-02 05:30:36 -06:00

@guillep2k commented on GitHub (Sep 9, 2019):

@lunny Why multiple repositories if we could use one repo with branches or tags?
From what I understand, currently the best resource file for any version of Gitea is the latest; meaning that the latest is compatible with all the previous versions.

The problem with custom/options/locale (which we may still support, no need to remove them) is that users can override whole files, not individual translations.

@guillep2k commented on GitHub (Sep 9, 2019): @lunny Why multiple repositories if we could use one repo with branches or tags? From what I understand, currently the best resource file for any version of Gitea is the latest; meaning that the latest is compatible with all the previous versions. The problem with custom/options/locale (which we may still support, no need to remove them) is that users can override whole files, not individual translations.

GiteaMirror commented

2025-11-02 05:30:36 -06:00

@lunny commented on GitHub (Sep 9, 2019):

meaning that the latest is compatible with all the previous versions.

I don't think so, some keys may added, deleted or changed.

Currently we already have multiple locale versions since all that files in gitea's repositories. The problem is we cannot change the old version translations, only master version could be allowed to change, otherwise it will result in unknow problem.

Multiple crowdin repositories will resolve the problem. When we addressed or are developing v1.10, we also could change v1.9.3 or v1.9.4's translation files.

@lunny commented on GitHub (Sep 9, 2019): >meaning that the latest is compatible with all the previous versions. I don't think so, some keys may added, deleted or changed. Currently we already have multiple locale versions since all that files in gitea's repositories. The problem is we cannot change the old version translations, only master version could be allowed to change, otherwise it will result in unknow problem. Multiple crowdin repositories will resolve the problem. When we addressed or are developing v1.10, we also could change v1.9.3 or v1.9.4's translation files.

GiteaMirror commented

2025-11-02 05:30:36 -06:00

@guillep2k commented on GitHub (Sep 9, 2019):

I see. I'm not familiar with Crowdin administration.

However, I still think we could use branches to handle the corresponding translations (eg. locale-v1.9.2, locale-v1.9.3 or locale-v10.0.0, and the user should install the closest to their installation, or create local brands taking changes from many sources.

That's the beauty of git: we don't need one "principal" branch, we can have many.

@guillep2k commented on GitHub (Sep 9, 2019): I see. I'm not familiar with Crowdin administration. However, I still think we could use branches to handle the corresponding translations (eg. `locale-v1.9.2`, `locale-v1.9.3` or `locale-v10.0.0`, and the user should install the closest to their installation, or create local brands taking changes from many sources. That's the beauty of git: we don't need one "principal" branch, we can have many.

GiteaMirror commented

2025-11-02 05:30:36 -06:00

@lafriks commented on GitHub (Sep 9, 2019):

I don't really see what this will solve :)

@lafriks commented on GitHub (Sep 9, 2019): I don't really see what this will solve :)

GiteaMirror commented

2025-11-02 05:30:36 -06:00

@gary-kim commented on GitHub (Sep 9, 2019):

We do need to put a system in place for backporting translations but I don't think putting the translations in another repo is the way to do it.

Just as an idea, do we have a way to mark a translation as deprecated but still keep it in the file? That way, we could use a system in which translations are only added and marked as deprecated if a translation gets changed or otherwise is no longer needed. Then we can backport translations freely without fear of breaking anything since all keys are still in the translation files so the translation commits can be set up to commit to all supported release branches. Then new translations can be released as part of the incremental updates.

@gary-kim commented on GitHub (Sep 9, 2019): We do need to put a system in place for backporting translations but I don't think putting the translations in another repo is the way to do it. Just as an idea, do we have a way to mark a translation as deprecated but still keep it in the file? That way, we could use a system in which translations are only added and marked as deprecated if a translation gets changed or otherwise is no longer needed. Then we can backport translations freely without fear of breaking anything since all keys are still in the translation files so the translation commits can be set up to commit to all supported release branches. Then new translations can be released as part of the incremental updates.

GiteaMirror commented

2025-11-02 05:30:37 -06:00

@guillep2k commented on GitHub (Sep 9, 2019):

Some examples here to try to convey the good points of the proposal.

This is what the users will see in their local installation

A new, internal user "system", will own one no-bare repository that has its origin set to gitea.com/gitea/gitea-locale:

When Crowdin updates the official translations, the local system pulls the corresponding branch from origin (e.g. `v1.9`, `master`, etc.):

When the user wants to perform some customization, they can just simply edit on their `local` branch (or perhaps a side branch can be easier to deal with):

A new Crowdin update will honor the user customizations (as long as there is no conflict)

The user can keep both versions, git controlled, with commit history, etc.

@guillep2k commented on GitHub (Sep 9, 2019): Some examples here to try to convey the good points of the proposal. ### This is what the users will see in their local installation A new, internal user "system", will own one _no-bare_ repository that has its `origin` set to `gitea.com/gitea/gitea-locale`: ![image](https://user-images.githubusercontent.com/18600385/64554772-6f330f00-d312-11e9-8774-faf74f4f42dd.png) ### When Crowdin updates the official translations, the local system pulls the corresponding branch from origin (e.g. `v1.9`, `master`, etc.): ![image](https://user-images.githubusercontent.com/18600385/64554792-778b4a00-d312-11e9-98e1-f3c731b843e8.png) ### When the user wants to perform some customization, they can just simply edit on their `local` branch (or perhaps a side branch can be easier to deal with): ![image](https://user-images.githubusercontent.com/18600385/64554862-91c52800-d312-11e9-8817-be04e8d38d5e.png) ### A new Crowdin update will honor the user customizations (as long as there is no conflict) ![image](https://user-images.githubusercontent.com/18600385/64554880-98ec3600-d312-11e9-80f3-de29f5c68535.png) ### The user can keep both versions, git controlled, with commit history, etc. ![image](https://user-images.githubusercontent.com/18600385/64554906-a6092500-d312-11e9-82ad-9bf90cd27ff1.png)

GiteaMirror commented

2025-11-02 05:30:37 -06:00

@guillep2k commented on GitHub (Sep 9, 2019):

One think I forgot to mention about this solution: updating the locale will no longer require to be the site admin and/or have ssh access. Admins can delegate this task to other people using the current teams structure.

@guillep2k commented on GitHub (Sep 9, 2019): One think I forgot to mention about this solution: updating the locale will no longer require to be the site admin and/or have ssh access. Admins can delegate this task to other people using the current teams structure.

GiteaMirror commented

2025-11-02 05:30:37 -06:00

@wxiaoguang commented on GitHub (Apr 25, 2023):

I think these problems are almost resolved at the moment

Currently translations lag one major version behind.

No behind anymore, and we have a backporter

Updated translations require upgrading Gitea or a manual procedure to download the latest version.

Just download the latest stable version, and it contains bug fixes, it could be good.

Maintaining local translations in sync with official is difficult and error-prone.

Users could have their own "locale" git repo for sync?

So I think this issue could be closed?

@wxiaoguang commented on GitHub (Apr 25, 2023): I think these problems are almost resolved at the moment 1. Currently translations lag one major version behind. No behind anymore, and we have a backporter 2. Updated translations require upgrading Gitea or a manual procedure to download the latest version. Just download the latest stable version, and it contains bug fixes, it could be good. 3. Maintaining local translations in sync with official is difficult and error-prone. Users could have their own "locale" git repo for sync? So I think this issue could be closed?

GiteaMirror referenced this issue

2025-11-02 12:27:23 -06:00

[PR #3919] [MERGED] Fix wiki redirects #17143

GiteaMirror referenced this issue

2025-11-02 12:30:05 -06:00

[PR #4065] [MERGED] Fix wiki redirects (#3919) #17223

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#3919

Proposal: move options/locale to a git submodule #3919

Motivations

1. Currently translations lag one major version behind.

2. Updated translations require upgrading Gitea or a manual procedure to download the latest version.

3. Maintaining local translations in sync with official is difficult and error-prone.

The proposal

On Crowdin and the main repository

On the Gitea installation

Immediate benefits

Future

Needs polishing?

This is what the users will see in their local installation

When Crowdin updates the official translations, the local system pulls the corresponding branch from origin (e.g. v1.9, master, etc.):

When the user wants to perform some customization, they can just simply edit on their local branch (or perhaps a side branch can be easier to deal with):

A new Crowdin update will honor the user customizations (as long as there is no conflict)

The user can keep both versions, git controlled, with commit history, etc.

When Crowdin updates the official translations, the local system pulls the corresponding branch from origin (e.g. `v1.9`, `master`, etc.):

When the user wants to perform some customization, they can just simply edit on their `local` branch (or perhaps a side branch can be easier to deal with):