No Description

git 205e90c0a0 add % advancement and command to check for unincluded languages		2 years ago
,lstdifflang	205e90c0a0 add % advancement and command to check for unincluded languages	2 years ago
,lstlang	888ffcb5f6 add new files	2 years ago
,lstlang_sorted	888ffcb5f6 add new files	2 years ago
LICENSE	651ce58db6 Initial commit	2 years ago
README.md	c6d1dd8f1a format fix	2 years ago
chklang	205e90c0a0 add % advancement and command to check for unincluded languages	2 years ago

SPDX-License-Identifier: CC-BY-SA-4.0

jitsi-translate-tools

The Jitsi-meet project don't currently have a scalable, easy to use solution to manage translations, like it used to when translate.jitsi.org was still around.

While the current situation persists, would be tranlators have to learn to be Javascript developers, a rather daunting task if one don't have any developer experience.

You will find here a script, chklang, to help to manage new translations, and instructions on how to use git and Github to send updated translations for inclusion in the Jitsi-meet project.

To use this tool and instructions, you will still need some Linux skills.

chklang needs python3 installed. Add it to a directory in the path. You can also copy ,lstlang and ,lstlangsorted, 2 scripts that display the current state of translations.

Make these scripts executable.

Use of chklang

help comes with chklang -h (or --help)

This document describes two different ways of using it.

The first is a simplified version using an existing Jitsi-meet server and the Jitsi-meet project web interface.

The second is the full-blown version using developer tools.

Mixing the two modes is possible.

In the following examples, the fictional language code ('ex') will be used.

Replace as needed by your favourite language code, like 'eo' for esperanto.

If you don't know it, you can find the supported languages list in the Jitsi-meet source. It's assumed that the language you want to manage is already supported, supporting a new language is not covered, only correcting and completing already existing translations.

1 - Simplified use on a Jitsi-meet server

1-A generate the new version

examine the situation for the language 'ex':

cd /usr/share/jitsi-meet

chklang ex

english language keys that can't be found in language 'ex' (to create)
raisedHandsLabel
number of keys to add 1

'ex' language keys that can't be found in english version (to be cleaned)
number of keys to purge 0

A json file consists of 'keys' in a hierarchical tree associated with values. In this case keys are symbols referred in the application's code, and values are the translated strings that are used when displaying the user interface in the appropriate language. You can then edit the lang/main-ex.json file to add the missing keys (if you use vi as editor, sudo vi lang/main-ex.json)

It is possible to generate the missing keys automatically with the -a (--auto-generate) switch:

chklang ex -a

new version created as /home/gp/main-ex.json, 1 new keys from which 0 were added from a previous version

When editing the new file (generated by default in the home directory), you will find '!!' at the beginning of the new values:

"raisedHandsLabel": "!!Number of raised hands",

these 2 !! characters can be useful to quickly go from a new added key to another, with your favourite editor's search tool. Remove them before translating the string.

You can then directly enable the new version by copying it to the lang/ subdirectory (use sudo since it's a protected directory).

Don't forget to use Alt-F5 or similar to empty the browser cache before testing the new language file.

Check that the localized version is actually used and your changes are taken in account.

If you are satisfied with your translation and want to send the changes to the Jitsi-meet project, you can then use the Github web interface as described below.

1-B register a Github account if needed, login and create a copy of the project

Go to the jitsi-meet project on Github and click the 'Fork' button (upper right). If you missed the previous login step, you will have to login at this point.

After a few seconds, you will see that Github has generated a copy of the project but under your own account, this copy is called the forked repository.

1-C send the modified version to the Jitsi-meet project

1-C-1 upload the file to your forked repository

click the down arrow on the 'Add file' button to display more options and select 'upload files'.In the following options below, select 'create a new branch'. Give a descriptive name to your new branch, such as 'updatelangex_fix'.
click on 'choose your files'. Select the changed main-ex.json file you created.
Enter in the box below 'commit changes' a description such as

fix(lang): update example translation

Select 'Create a new branch' (instead of the default option Commit directly to the master branch) Give to the new branch a descriptive name such as 'updatelang_ex'.
Then click on 'Propose changes'.

A new screen titled 'Open a pull request' appears.

DO NOT click on 'Create pull request'. (this would create a pull-request in your own repository)

Click on the 'Code' link instead.

1-C-2 generate the pull-request to the Jitsi-meet project

You will see a message on a yellow background saying that the new branch ('updatelang_ex' in our example) had recent pushes.

Click then on the 'Compare & pull request' button.

A new screen displays titled 'Open a pull request' appears.

However this time the target repository (check the upper left of the screen) will be the jitsi/jitsi-meet project.

Click on 'Create pull request'.

1-D: bother: the CLA unpleasantness.

You have to assign the legal rights on your contribution to the Jitsi-meet organization.

An automated message will be added to your pull-request by a thingy called jitsi-jenkings (this is not a human being, it's an automated agent, a so-called bot) asking you to sign the CLA (Contributor License Agreement).

You have to provide your name and details and a working mail address. This can be any working email address but if you don't use the same address as the one used in your Github contribution (as set in the previous step 2-B-2) it may slow the (manual) processing of this step.

Note that to add insult to injury - because in other even very lawyery projects, CLA are asked only for code contributions, not translation changes, the legal risks being usually deemed unsignificant - every time that you want to send a new update to the localized language, this message will be generated again.

Oh well.

I can't help you much with this process - I don't quite remember all the details, but it involves scanning a real pen on paper signature and uploading the image file.

Read the document anyway (or forward it to the appropriate lawyer if you work for a business, it's a different CLA) before signing.

Once the CLA is recorded by the Jitsi sponsor, you have to add a comment to the pull-request saying so.

Don't add the comment saying it has been approved if you don't get confirmation it has been done (a certificate in a PDF file).

1-E: wait for Jitsi-meet developers to approve and merge your change.

This can be quick if you are in luck, or often take several days. I have seen translation pull-requests languish for weeks (but it's not common unless the change is ignoring basic rules or being superseded by another change that has been merged in the mean time).

Be aware that if you have used chklang -a, the file will have been reformatted.

You can even use chklang to change indentation. In this case the formatting changes will cover the whole file.

This will create a huge change (a big 'diff') to read.

Always remember that reading a pull-request is work.

THIS . IS . WORK !

So if you make it unnecessary painful for the Jitsi developer, you are taking the risk that your pull-request will be let to languish for longer.

Possibly for ever.

There is no formal requirement that changes requests to the Jitsi-meet project separate formatting from functional changes, but it's bad form anyway in my humble opinion.

So avoid it if you can, or keep the formatting changes light if you also change function (that is, actual translation changes).

1-F: your pull-request has been merged

You will see after the pull-request in the jitsi/jitsi-meet repository:

xxxxx approved these changes N days ago (or N hours ago...)

@xxxxx xxxxx merged commit 123456789 into jitsi:master N days ago

where xxxxx is the alias of a Jitsi-meet developer.

Congratulations !

Your changes have been integrated in the current Jitsi-meet version, the so-called 'master' version, or 'unstable'. You will be able to see it on alpha.jitsi.net, or on your local server if it's running unstable and you upgrade it to latest version.

After the merge message, you will see in the Github interface a message saying:

Pull request successfully merged and closed

The .... branch can be safely deleted. (your branch)

Click on the 'Delete branch' button.

Job is done, you are all set to translate future new messages when they are created by the Jitsi-meet project.

1-G: your pull-request has some mistakes and a Jitsi-meet developer asks for a correction before merging it.

Note that you have the right to disagree and object to the developer's remarks if it's something you know better (it's only likely if it pertains to your favourite language, if it concerns specific computer problems like file formatting you have better to do what's asked from you without grumbling).

If you want to object, just add a comment to your pull-request in the jitsi/jitsi-meet Github repository.

If not, create a new language file version using the same procedure as in 1-A

Make sure that everything is correct and that the file still works as modified and conforms to what was asked.

Then start again in step 1-B, but instead of the main branch in your forked Jitsi-meet repository, upload the modified file to the new branch that you created in step 1-C.

If needed, use the branch selector (the left button in the row where there is the green 'Code' button).

After the upload is finished, your branch will be 2 commits ahead of the main branch on jitsi/jitsi-meet.

That's all there is to modify your pull-request.

Now go to step 1-E again.

2 - Use on a workstation (with developer tools)

The general idea is to copy the Jitsi-meet project (a repository in Git parlance) to your Github account, create a local copy (repository) of this copy on your computer, change here the localization file (lang-ex.json in this example), use the local repository management tool 'git' (man git) to send the change to your Github repository, then from the Github repository generate a change request ('Pull-request' in Github parlance) to the Jitsi-meet repository, and the 'pull-request' will be 'merged' (included) into the project by a Jitsi-meet developer. It is that simple, just read the 12 following sections for details :-)

2-A: register a Github account if needed and login

Go to the jitsi-meet project on Github and click the 'Fork' button (upper right).

You will be redirected to your new personal version of the jitsi-meet repository.

2-B: create an updated local file

2-B-1: setup

On a Linux workstation (or possibly some emulated solution):

install git (sudo apt install git on a Debian-like system) and the openssh client (sudo apt install openssh-client) if necessary.

then

git clone git@github.com:mynewuser/jitsi-meet.git

Git will then generate a new 'jitsi-meet' directory on your local disk after a minute or so (there is a lot of data to download from Github).

Note on network configuration: for this to succeed, your computer/firewall will have to be able to connect to github.com on the port 22 (SSH).

You may find many how-tos on Internet advising to git clone with a http address but they are either outdated, or adapted to cases where users don't have to send changes to Github, something for which ssh is now needed.

2-B-2: prepare the new local environment

Change to this new directory

cd jitsi-meet

First, set your name and email information:

git config --local user.name "mynewuser"

git config --local user.email "44170243+mynewuser@users.noreply.github.com"

→ in the email field, you can either:

use a 'real' email address (where you will need to be able to actually receive mail) or
use a github managed email address that you can get from your Github account settings by going to the 'Emails' part and grab it from the 'Keep my email addresses private' section. This is not necessarily the email address that you had to provide to create the Github account.

Second, create a new git 'branch' (version) with something like:

git checkout -b translatefix

You can of course name your new branch any name you want, such as 'translatelangex_fix' if 'ex' is your language code.

This is needed to facilitate the management of sending changes to the Jitsi-meet project.

Use 'git status' to confirm that you are on the correct branch. It should display something like:

On branch updatelangex_fix
nothing to commit, working tree clean

2-B-3: edit the language file

You can then directly edit the lang/main-ex.json file using your favourite editor, or use the language file you tested on your Jitsi-meet server with the previous section, or use chklang like this:

chklang ex -a -o lang

the localized language file (that is, something like 'main-ex.json' in the example above) in the lang/ subdirectory will be updated.

** Warning: -a will REFORMAT the whole file and can potentially generate a huge change to send to the Jitsi-meet project, that may be not well received. You can always edit the file manually if this is a problem **

If you use chklang -a, take care to translate ALL the values beginning by '!!'.

The local branch (that is, updatelangex_fix in our example) will then be ready to be validated.

2-B-4: inform git that your local changes are complete

git commit -a

Git will then open a new window in the default git editor to let you enter a comment for your change. This is necessary to explain to the Jitsi-meet developers what your change is about.

You can enter something like:

fix(lang): update example translation.

Replace 'example' by your favourite language (esperanto, if you are trying to fix the esperanto translation).

then save the edit (Ctrl X if the editor is 'nano').

Use 'git log' to confirm that your changes are correct in your local git directory.

You should get something like that:

commit ca227df7ec5cd657d1fbc2da711af7b639450d3e
Author: mynewuser <44170243+mynewuser@users.noreply.github.com>
Date:   Sun Dec 19 08:54:53 2021 +0100

    fix(lang) update example translation.

commit fb843a7ecf3ecfacf0b33452ed526ccf7238d2f9

(followed by all the commits by other contributors...)

2-C (optional) : test the updated language file

You may consider testing the file on a real Jitsi-meet project if you have one by uploading it to /usr/share/jitsi-meet/lang and trying to access a room on the server.

Don't forget to use Alt-F5 or similar to empty the browser cache.

Check that the localized version is actually used and your changes are taken in account.

2-D: send the updated language file to your forked personal Github project

For Github to accept your change, you need to:

2-D-1: generate a new personal SSH key

type the following - take care to NOT let the SSH key file (-f switch) in your git repository !

ssh-keygen -t ed25519 -f id_github

(type 'enter' 2 times to answer to the prompt about a passphrase)

This will generate

a private key in the file named in this example 'id_github' and
a public key in the file named 'id_github.pub'.

The public key will have to be entered in the Github account to validate the changes created by git using the private key.

2-D-2: set the public key in your Github account

This can be done so:

navigate to the account settings.

Among a big list of options to the left, click the 'SSH and GPG keys' option.

Click 'New SSH key'.

Add a title to your convenience to identify the key,

In the box below, enter the content of the 'id_github.pub' file. You can safely skip the last part identifying your computer.

Click the 'Add SSH key' button below to validate.

If the Github user interface don't complain, this part is successfully done.

2-D-3: set your local git installation to use the SSH key when sending changes to your Github forked repository.

This is done with the private SSH key.

eval "$(ssh-agent -s)"

→ this will launch the ssh-agent application that will proceed to get the private key when asked by git. This will be needed again if you restart the whole process another time, so you may want to set this to be restarted with your session.

ssh-add id_githubed

→ this will add your private key to the ssh configuration so that ssh-agent will use it when called by git to validate the changes you are asking to send to Github.

2-D-4: finally send the changes

git push origin updatelangex_fix

this will create the updatelangex_fix branch in your forked Github repository.

This branch (that you can see in the Github interface) will hold your modified file with all the updated translations.

2-E: generate the pull-request to the Jitsi-project

If you were already logged in to your Github account and were having the new repository displayed, the Github user interface will then inform you that changes were pushed to the repository, and a new button will have appeared to allow you to 'Compare & pull request', click it.

If you were not, login to your Github account and go to your forked Jitsi-meet project to do the same operation.

The Github user interface will then display a preliminary screen to prepare the pull-request.

It should display 'able to merge. These branches can be automatically merged'.

If not it's a problem, changes have been done to the Jitsi-meet project while you were working on all the previous steps. This is not a likely occurence, but it can happen and in this case, you may have to step back, cancel the pull request and start again.

If things go well, you should see 'able to merge' and below should appear the commit message you will have entered in step 2-B-4.

Below you have an opportunity to add an additional comment. This is not mandatory but there may be some special information about your change. I use it to pre-empt the following step.

Finally click the Create pull request button below.

You will be redirected to the new created pull-request in the Jitsi-meet project for the Jitsi organization.

2-F: bother: the CLA unpleasantness.

You have to assign the legal rights on your contribution to the Jitsi-meet organization.

An automated message will be added to your pull-request by a thingy called jitsi-jenkings (this is not a human being, it's a bot) asking you to sign the CLA (Contributor License Agreement).

Oh well.

I can't help you much with this process - I don't quite remember all the details, but it involves scanning a real pen on paper signature and uploading the image file.

Read the document anyway (or forward it to the appropriate lawyer if you work for a business, it's a different CLA) before signing.

Once the CLA is recorded by the Jitsi sponsor, you have to add a comment to the pull-request saying so.

Don't add the comment saying it has been approved if you don't get confirmation it has been done (a certificate in a PDF file).

2-G: wait for Jitsi-meet developers to approve and merge your change.

Be aware that if you have used chklang -a, the file will have been reformatted.

You can even use chklang to change indentation. In this case the formatting changes will cover the whole file.

This will create a huge change (a big 'diff') to read.

Always remember that reading a pull-request is work.

THIS . IS . WORK !

So if you make it unnecessary painful for the Jitsi developer, you are taking the risk that your pull-request will be let to languish for longer.

Possibly for ever.

There is no formal requirement that changes requests to the Jitsi-meet project separate formatting from functional changes, but it's bad form anyway in my humble opinion.

So avoid it if you can, or keep the formatting changes light if you also change function (that is, actual translation changes).

2-H: your pull-request has been merged

You will see after the pull-request in the jitsi/jitsi-meet repository:

xxxxx approved these changes N days ago (or N hours ago...)

@xxxxx xxxxx merged commit 123456789 into jitsi:master N days ago

where xxxxx is the alias of a Jitsi-meet developer.

Congratulations !

You can then clean your setup by following these steps in your local jitsi-meet directory.

git checkout master

git push --delete origin updatelangex_fix

git branch -D updatelangex_fix

this will set the main branch as the current one (it's not possible to delete the current branch), delete the remote branch in your forked Github repository, and delete the local 'branch' in your jitsi-meet directory.

This is not strictly necessary but will help to manage ulterior translations, because...

You will have then just to wait a few days for a Jitsi-meet developer to do changes to the main.json file and you will have to do new translation updates.

See below step 2-K for the (simplified) process to repeat the operation

2-I: your pull-request has some mistakes and the Jitsi-meet developer asks for a correction.

If you want to object, just add a comment to your pull-request in the jitsi/jitsi-meet Github repository.

If not, go to your local git repository (jitsi-meet directory) and edit directly the language file with your favourite editor.

Make sure that everything is correct and that the file still works as modified and conforms to what was asked.

Use then

git commit -a

and enter a new comment (as a minimum something like: 'requested changes') then save. Then:

git push origin updatelangex_fix

Git will then send the new modified version to Github. Your pull-request will be updated and a new line ('commit') will appear with the requested changes.

Go to step 2-G.

2-J: the waiting phase (2-G) has been so long hat the main.json international english file has been changed by another Jitsi-meet developer

Before a Jitsi-meet developer has merged your pull-request.

Argh.

Note that it is not necessary to do anything if the main.json international english reference file has not been changed, the other changes are irrelevant.

But changes to the main language file are frequent.

You can either shrug it off and let it be, and let commit the existing changes you sent (just wait in this case, so go to step 2-G), or you may want to include the new changes in the existing pull request, so that it will not be already partially obsolete when it will be (eventually) merged.

Go first to your forked Github repository, being logged in to Github (very important). You will see a message saying:

This branch is (xx) commits behind jitsi:master.

You will also notice a new button saying 'fetch upstream'.

Clicking the button will do as it says, that is, update the 'master' branch in your forked Github repository from the 'master' (main) branch in the jitsi/jitsi-meet project.

This will not touch your branch because the Jitsi-meet project don't know anythihg about it.

Go to your local git repository (the jitsi-meet directory on your computer).

git checkout master

-> this will set the main branch as current (not your changed branch).

git pull

-> this will pull all the new changes (including the new main.json international english file).

then switch back to your special modified branch

git checkout updatelangex_fix

git pull --rebase origin master

this will merge in your modified branch all the changes in Jitsi-meet master branch, including the modified main.json file, and set your change before all the new merged changes coming from the Jitsi-meet project activity.

Verify it with 'git log'.

You can then edit again the lang/main-ex.json file to add the new missing translations.

Once this is done, there are 2 possibilities.

a) your pull request has been approved (but NOT merged). How can this be possible ?

Truth is, I don't know, but my guess is that is related to the pecking order in the Jitsi-meet project, some developers can have a more or less accomplished knowledge of a given language and can then approve the changes (that have then deemed good to include) BUT don't have the necessary rights to commit contributions from external contributors.

In this case it's best to add a new commit.

git commit -a

(enter a new comment along the lines of 'added new translations from changes in main.json')

save, then

git push origin updatelangex_fix -f

in the pull-request in the Jitsi/jitsi-meet Github repository, you will see a message saying that you dismissed the stale review of the Jitsi-meet developer having approved your changes, followed by a new commit with the updated translations.

Your new changes will have to be approved again (if there are only a few lines changed it could be hopefully a quicker process) and merged.

Go to step 2-G
b) your pull request has not even been approved yet. In this case, it's an unnecessary hassle for the Jitsi-meet developer to have to read two different commits.

Use then

git commit -a --amend

the editing window will then display the original commit message, save it without any change.

git push origin updatelangex_fix -f

you will then see on your pull-request that you 'force-pushed' new changes.

Like the original version, the modified pull-request has yet to be approved and merged.

Go to step 2-G

2-K: your changes have been included, however new strings have been added, and you want to update the translation again.

In this case restart from step 2-B-2 (you can skip the part about setting the user name and mail since you are restarting from the same local repository, they are already set)

Otherwise, everything is the same except that you don't have to sign a second time the CLA, just say that you did already.

2-L: in case of errors.

When using git, mistakes are easy to do.

If you have done a local mistake (before sending anything to your Github forked repository), it's always possible to destroy your local repository and git-cloning again your forked Github repo.

It will work, even if there is a pending pull-request.

If your mistake is sent to the Jitsi-meet project but not yet merged, it's always possible to delete your pull-request, delete your local repo, even destroy the forked Github repository (this will delete automatically the pull-request), and redo partly or totally everything.

Once your change is merged, your only option is to create a new pull-request to fix the mistakes (don't forget to delete your modified branch if you want to use the same branch name again as in 2-H, and restart in 2-K)

2-M: Good luck !

it's now up to you to get a good translation of your favourite language in Jitsi-meet.

README.md