Gambas Documentation
Documents

How To Translate Gambas

Last edit: 2024-07-06 by gbWilly

1. Create a gitlab account (online) and make your own fork of gambas

Please take some time to first create an account on Gitlab, next fork gambas to your account (all done in Gitlab interface online), before you continue reading, as these are needed to translate gambas.

How to create a gitlab account and fork gambas is explained in detail here /wiki/howto/contribute#t1.

2. On your local system

2.1 Cloning your forked repo

I'm used to using git in command line, but Gambas IDE offers possibilities to manage git. I will explain the command line method I am used to, but will show the IDE option as well (show, not explain)

Make sure git is installed on your sytem as you will need it.

More on installing and using git and gitlab can be found here: How to deal with Git and Gitlab for Gambas
Advised is to take some time to get familiar with some basics of git and gitlab, even if you can use the Gambas IDE, some basic understanding of git is useful.
Download the git cheat sheet (pdf) for a good overview of some important git commands.

Next open a terminal on your system and do as follows: 

$ mkdir translate
$ cd translate
$ git clone [email protected]:<yourusername>/gambas.git
$ cd gambas && ls

This should show you the complete gambas source.

2.2 Preparing to translate

In the terminal we have some work before starting to translate. It all depends on if you translate from master branch or from stable branch. There are some things that are clever to do for both before getting started. In the terminal you left of do as follows: 

$ git config --global user.email [email protected]
$ git config --global user.name your name
$ git remote add upstream https://gitlab.com/gambas/gambas.git

What you do here is set your mail and name and add a remote named upstream linked to official gambas on gitlab.

Some clarification:

  • upstream master points to masters at https://gitlab.com/gambas/gambas.git (Original Gambas at GitLab)

  • upstream stable points to stable at https://gitlab.com/gambas/gambas.git (Original Gambas at GitLab)

  • origin master points to master at https://gitlab.com/<yourusername>/gambas.git (your GitLab fork of Gambas on GitLab)

  • origin stable points to stable at https://gitlab.com/<yourusername>/gambas.git (your GitLab fork of Gambas on GitLab)

  • master and stable point to your local clone of your GitLab repository (your local copy of your GitLab Gambas repository)

2.2.1 Update local copy with upstream, and update origin

If translating from master

In terminal continue as follows: 

$ git pull upstream master
$ git push origin master

This will make sure you are in sync with latest on upstream master at https://gitlab.com/gambas/gambas.git and that these changes are pushed to your fork at gitlab (being origin master).

If translating from stable

In terminal continue as follows: 

$ git checkout stable
$ git pull upstream stable
$ git push origin stable

This will make sure your switch to stable and it is in sync with latest on upstream stable at https://gitlab.com/gambas/gambas.git and that these changes are pushed to your fork at gitlab (being origin stable).

It is also possible to switch from branch in Gambas IDE when you have the project opened. This is the same as git checkout See screenshot below.


Gambas3 IDE switch branch

Be aware that just by opening a project and changing to another branch in IDE it might ask you to stage or commit files before changing from branch.


Gambas3 IDE switch branch asking to commit or stage the files

2.2.2 Create a new branch for doing the translations in

If translating from master

In terminal continue as follows: 

$ git checkout -b master-nl

You created a new branch master-nl (a copy of master with added nl for Dutch language in my case) to start translating in. Be aware that you are now working in branch master-nl.

If translating from stable

In terminal continue as follows: 

$ git checkout -b stable-nl

You created a new branch stable-nl (a copy of stable with added nl for Dutch language in my case) to start translating in. Be aware that you are now working in branch stable-nl.

Some clarification added to previous:

  • upstream master points to masters at https://gitlab.com/gambas/gambas.git (Original Gambas at GitLab)

  • upstream stable points to stable at https://gitlab.com/gambas/gambas.git (Original Gambas at GitLab)

  • origin master points to master at https://gitlab.com/<yourusername>/gambas.git (your GitLab fork of Gambas on GitLab)

  • origin stable points to stable at https://gitlab.com/<yourusername>/gambas.git (your GitLab fork of Gambas on GitLab)

  • master and stable point to your local clone of your GitLab repository (your local copy of your GitLab Gambas repository)

  • master-nl points to your local copy of your local master (there is no online branch master-nl in your GitLab Gambas repository)

  • stable-nl points to your local copy of your local stable (there is no online branch stable-nl in your GitLab Gambas repository)

We will create this online master-nl and/or stable-nl in a later part of these instructions.

The advantage of making a local copy of your own repository is that it leaves your own local master and stable untouched (and thus your origin master and origin stable as well). This will make it easier to keep your repository up to date with upstream without any conflicts.

2.3 What to translate

Not all needs translation, but there are quite some things that do. And some tend to be translated in many languages, others not so. So let's start with an overview of what needs translating.

In this instruction I presume that the translate folder where you cloned to, is created in your home folder. So, I will refer to it as Cloned folder being home/username/translate/gambas.

Desktop and mime files

In Cloned folder there are a few files that need translating. These are the desktop file and some mime files and are often forgotten. You translate them by opening a text editor.
They are located at:

  • app/desktop/gambas3.desktop

  • app/mime/application-x-gambasscript.xml

  • app/mine/application-x-gambasserverpage.xml

The screens below should make somewhat clear what to do to translate them for your language.


gambas3.desktop file


application-x-gambasscript.xml file

Gambas components and IDE

These translations you do by opening Gambas IDE and in IDE open those parts/components of Gambas that need translation.
From menu Project/Translate you can do the translations for your language.

Make sure that your installed gambas has your name and e-mail configured in menu Tools/Preferences/Identity as this is used in the translation files, to know who translated.

When you open IDE you browse to the Cloned folder and open one of the following gambas projects.
This is a complete list of all non components that need translation:

  • app/.src/gambas3

  • app/.src/gbs3

  • app/.src/gambas-wiki

  • app/.src/gambas3-selftest

  • app/.src/gb.wiki

This is a complete list of all components that need translation:

  • comp/.scr/gb.args

  • comp/.scr/gb.db.form

  • comp/.scr/gb.eval.highlight

  • comp/.scr/gb.form

  • comp/.scr/gb.form.dialog

  • comp/.scr/gb.form.editor

  • comp/.scr/gb.form.midi

  • comp/.scr/gb.form.print

  • comp/.scr/gb.form.terminal

  • comp/.scr/gb.gui.base

  • comp/.scr/gb.highlight

  • comp/.scr/gb.net.pop3

  • comp/.scr/gb.report

  • comp/.scr/gb.report2

  • comp/.scr/gb.term.form

  • comp/.scr/gb.util

  • comp/.scr/gb.web.feed

  • comp/.scr/gb.web.gui

2.4 How to translate

Translating comes down to opening above mentioned projects in Gambas IDE, go to menu project/translate and provide translation for your language by translating missing string.

If your language is missing you can opt for New, select the language you want to translate to and a new translation file is created to start translating.


Gambas IDE New translation.

For detailed instruction on how to do translation in Gambas IDE see How To Translate A Gambas Project.

If you are new to translating make sure to add your name, e-mail and language you translate for to the file AUTHORS in the Cloned folder.

While translating keep track of what you do in a text file and make your commit log for later.
An example of commit for desktop and mime files translation, update of translation for IDE and gb.gui.base and a new translation for gb.highlight 

[DEVELOPMENT ENVIRONMENT]

* NEW: Dutch translation updated
* NEW: Added Dutch translation to gambas3.desktop file
* NEW: Added Dutch translation to application-x-gambasscript.xml
* NEW: Added Dutch translation to application-x-gambasserverpage.xml

[GB.GUI.BASE]

* NEW: Dutch translations updated

[GB.HIGHLIGHT]

* NEW: Dutch translations

More info on commit messages can be found here /wiki/howto/contribute#t4 and here /wiki/howto/contribute#t7

2.5 Update your own fork with translations

Once all translations are done you need to stage them and next commit them to be pushed to your fork (either origin master or origin stable.

Always make sure you know what branch you are working in and what branch you are pushing your commit to, not to mess things up.

In terminal continue as follows: 

$ git status                    --> to view files that are changed and need to be staged
$ git add .                     --> to add all the files that have changed for commit
$ git commit                    --> write your commit log here
$ git push -u origin <branch>   --> push your new branch to your fork (you can add stable-nl or master-nl for <branch>, according to the branch you are on)

Once all this is done your fork at gitlab should be updated with your commit.

3. On your GitLab account (online)

3.1 Create a merge request for upstream

For this you need to login to gitlab.

If you translated master

If you go to your forked gambas project https://gitlab.com/yourgitlabusername/gambas you will be in master branch. So, if you did your translations in master-nl and pushed them to your gitlab fork, you can do a merge request on this screen, to merge your yourgitlabusername/master-nl into gambas/master.

If you translated stable

If you go to your forked gambas project https://gitlab.com/yourgitlabusername/gambas you will be in master branch. Select stable-nl from the dropdown box to change to stable-nl. So, if you did your translations in stable-nl and pushed them to your gitlab fork, you can do a merge request on this screen, to merge your yourgitlabusername/stable into gambas/stable.

Be aware that when you hit request you will need to select stable as destination on gambas for your merge request as default merge requests use master!!!.


GitLab select branch stable

When doing the merge request, fill in some notes on what this merge request is about. If somebody comments on your request you should get a notification.

Next wait for the merge to happen or some comment given for some more details or whatever is needed/required.


GitLab merge request

3.2 Review your merge request for upstream

If later you want to review your merge request, you can, as long as the merge isn't done, go to your fork of the repository and click the button View merge request (see screenshot below).


GitLab view merge request

On above screen if you would push update fork, changes from upstream master would be merged into your origin stable, leading to a mess, as your origin stable and upstream master would be merged into your origin stable! So, only push that button on the GitLab interface if you are in your origin master branch.

Remember you are the fork and if you just made translations in stable, you do not want any exterior force to mess with your fork (especially not on your own invitation...).

4. Some useful help

4.1 What branch am I in?

In the terminal: 

$ git branch


Terminal what branch you are on

In Gambas IDE


Gambas3 IDE what branch you are on

4.2 Messed up a branch and want a clean start?

In the terminal (say you messed up stable): 

$ git checkout stable
$ git pull upstream stable
$ git reset --hard upstream/stable
$ git push origin stable --force

If --force fails try: 

$ git --config http.postBuffer 524288000
& GIT_CURL_VERBOSE=1 git push origin stable --force

This will give a clean stable from upstream stable and force pushes this to your fork origin stable. All translations done before you git reset --hard you will be lost!

4.3 More help with git

More help on using git can be found in the Git Reference and the Git Book.
Both are accessible online.

Page revisions

June 14th, 2024: How To Translate Gambas - W. Raets (gbWilly)
 June 16th, 2024 - W. Raets (gbWilly)
 
- Added a note on adding translator name to AUTHORS file
- Some rearranging for better layout
June 17th, 2024 - B. Steers
 
- Added brackets to titles for indexing
June 17th, 2024 - W. Raets (gbWilly) 
- Added brackets for 'Page revisions' as well
June 21th, 2024 - W. Raets (gbWilly) 
- Changed instruction to do translations on a local copied branch of either master or stable
- Added "Create a new branch for doing the translations in"
- Added screen on switching branch in IDE and request for commit/stage files happens
June 22th, 2024 - W. Raets (gbWilly) 
- Added some content to "Create a new branch for doing the translations in"
July 6th, 2024 - W. Raets (gbWilly) 
- Removed info from "Update your own fork with translations" as not practical when pushing using -u
- Added "More help with git"