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.
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
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
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:
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
- Added brackets to titles for indexing
- Added brackets for 'Page revisions' as well
- 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
- Added some content to "Create a new branch for doing the translations in"
- Removed info from "Update your own fork with translations" as not practical when pushing using -u
- Added "More help with git"