Closed
Opened by dev1fanboy @dev1fanboy

Translation primer

This is the primer on using git and translating.

Introduction

When they are ready, contents for this wiki end up on devuan.org for perusal by the many people who visit there and need information on getting setup.

Pages to translate

Choose from the following pages. Frozen pages are less work to translate and maintain, active pages are much more prone to changes and if you choose to translate them you will need to change them often to keep up with the latest changes.

Frozen pages:

Active pages:

Documenting changes

In every case you should credit yourself on the page you translated. For example:

Translation by your name

At the top or near the bottom of each page.

This should be enough to comply with CC by SA, and others will be able to copy your work with cloning from git if they wish to.

I strongly encourage collaboration, especially in git where that is easy to do. In that case, you should also include anyone else who worked on that document.

Translation by your name with improvements by their name

If you're working with git you will need to use commit messages to make your changes clear as well. This will be explained below.

Using git

We will focus first on creating the branch for your language. We will then talk about going about the translation work with git.

Create a git account on git.devuan.org and see the guidance on setting up your keys here and then again here . If you're unable to get past this step don't panic, you will be able to use https instead provided you enter your username and password each time. If you do get your keys setup you will not have to do that when commiting your changes.

First clone the repository.

git clone git@git.devuan.org:dev1fanboy/Upgrade-Install-Devuan.git

Or if you could not setup your keys for some reason use the https version.

git clone https://git.devuan.org/dev1fanboy/Upgrade-Install-Devuan.git

Every branch should use a two letter language code hereafter known aslc.

We can use one command to create a branch and switch to it immediately.

git checkout -b lc

Then make the directory to work with.

mkdir lc

Copy the file(s) you wish to work with into the directory you just created, leaving the name intact.

cp filename.md cl/

Now you have those files copied, do not start work on them yet as it's helpful to first push your branch to gitlab.

Add the new files to the list of changes that git will push back to the repository.

git add *

Now commit your changes using git-commit. The repository will not be written to yet.

git commit -a

Enter a commit message. It could be something like:

Created the es branch for Spanish translation.

Now push your changes to setup the branch on gitlab.

git push

That's it, your branch will be created. If you didn't setup your keys you will be asked to provide your login information.

Translating

Now you can start translating.

Use your favourite editor to work on the page you want to translate.

editor lc/filename.md

When you are done repeat the process as above.

git add lc/*

Then commit.

git commit -a

Then push.

git push

That's it, translation has been submitted.

Updating branches

You should regularly update your branches against master, especially just before you start translating pages as they may have been updated.

First checkout the master branch.

git checkout master

Then update it against the remote branch.

git pull

Then switch back to the branch you're working on.

git checkout lc

Then update it against the master branch.

git rebase master

Finally push back your changes.

git push

Working with markdown

There are many resources available for working with markdown out there, particularly you want those that refer to git or GFM (git flavour markdown).

Merging

When you are done translating a page or set of pages, you can merge to the development branch which will in turn be merged with master regularly.

Merge requests can be made by looking at the branches then making a merge request against the branch you want, development in this case.

  • dev1fanboy @dev1fanboy changed milestone to Include translations on Devuan.org ·

    changed milestone to Include translations on Devuan.org

  • Menelaos Maglis
    Menelaos Maglis @mmaglis ·

    [EDIT] I add below the complete sequence of the above commands and the issues I faced. The el branch was existing (initially created through the web interface) and contained some translated files already. This is the use case, when a new translator joins the effort and tries to clone the branch to work on it.

    git clone git@git.devuan.org:dev1fanboy/Upgrade-Install-Devuan.git

    This creates directory Upgrade-Install-Devuan. One has to change into this directory to run further git commands. 

    git checkout -b el
mkdir el

    I then copied several files from master into el branch that were not existing there.

    cp <missing-files>.md el/

    git add *

git commit -a
[el ab2e915] Add new files to be translated to Greek
 10 files changed, 1033 insertions(+)
 create mode 100644 el/dbus-free-software.md
 create mode 100644 el/debloating-recommends.md
 create mode 100644 el/devuan-without-dbus.md
 create mode 100644 el/jessie-install.md
 create mode 100644 el/jessie-minimal-install.md
 create mode 100644 el/migrate-jessie-minimalism.md
 create mode 100644 el/migrate-to-ascii.md
 create mode 100644 el/minimal-xfce-install.md
 create mode 100644 el/openbox-guide.md
 create mode 100644 el/upgrade-to-ascii.md

git push
fatal: The current branch el has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin el

To git.devuan.org:dev1fanboy/Upgrade-Install-Devuan.git
 ! [rejected]        el -> el (non-fast-forward)
error: failed to push some refs to 'git@git.devuan.org:dev1fanboy/Upgrade-Install-Devuan.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

git pull

There is no tracking information for the current branch.
Please specify which branch you want to merge with.
See git-pull(1) for details.
    git pull <remote> <branch>
If you wish to set tracking information for this branch you can do so with:
    git branch --set-upstream-to=origin/<branch> el

git pull git@git.devuan.org:dev1fanboy/Upgrade-Install-Devuan.git el

From git.devuan.org:dev1fanboy/Upgrade-Install-Devuan
 * branch            el         -> FETCH_HEAD

Merge made by the 'recursive' strategy.
 chroot-install-environment.md    |   4 +-
 el/.gitkeep                      |   0
 el/README.md                     |  43 +++++++++++++++++
 el/chroot-install-environment.md |  67 ++++++++++++++++++++++++++
 el/full-disk-encryption.md       |  76 +++++++++++++++++++++++++++++
 el/general-information.md        | 100 +++++++++++++++++++++++++++++++++++++++
 el/migrate-to-jessie.md          |  78 ++++++++++++++++++++++++++++++
 el/minimal-xorg-install.md       |  94 ++++++++++++++++++++++++++++++++++++
 el/network-configuration.md      |  64 +++++++++++++++++++++++++
 network-configuration.md         |   8 +++-
 10 files changed, 531 insertions(+), 3 deletions(-)                                                                                                           
 create mode 100644 el/.gitkeep
 create mode 100644 el/README.md
 create mode 100644 el/chroot-install-environment.md
 create mode 100644 el/full-disk-encryption.md
 create mode 100644 el/general-information.md
 create mode 100644 el/migrate-to-jessie.md
 create mode 100644 el/minimal-xorg-install.md
 create mode 100644 el/network-configuration.md

    Is there something wrong on my side or the page instructions need editing?

    Otherwise, the guide is good for quick on-boarding translators. Perhaps, each language could append a section with language specific instructions.

    I think we do need to distinguish between starting a new language translation setup and contributing to an existing one.

    Edited by Menelaos Maglis
  • dev1fanboy
    dev1fanboy @dev1fanboy ·

    I think you possibly went in the wrong order there. It should be:

    git checkout master

    git pull

    git checkout el (standing in for lc)

    git rebase master (this will sync your branch with master, note the need to pull it first as above)

    then git push

    In any case, I will look soon and update all branches, and add anything that's missing.

    Edited by dev1fanboy
  • Linuxito
    Linuxito @linuxito ·

    I'm using (instead of rebase): 

    git checkout master 
git pull
git checkout es
git merge master es
git push origin es

    To keep "es" updated with "master".

    I didn't have any problem with that but, is this workflow right or wrong? What is the difference between rebase and merge?

  • Linuxito
    Linuxito @linuxito ·

    One question,

    I didn't credit myself on the pages I've translated, and being a requisite to comply with the license, I will do it next.

    Question is: the phrase "Translation by xxxx" should be in English or in the target language (i.e. "Traducido por xxxx")?

    Thanks!

  • Menelaos Maglis
    Menelaos Maglis @mmaglis ·

    I translate also the<sub>section and point the URL to thedeed.<language code>variant.

    Therefore, in my opinion, the phrase about the translation credit and the name should naturally be in the target language.

    Edited by Menelaos Maglis
  • dev1fanboy
    dev1fanboy @dev1fanboy ·

    @linuxito it should be OK to put it as "Traducido por.." and that should cover you for all changes, it's just that git will automate that with commit messages as well.

    It is OK to merge master into your working branch as well, it should have the same result. As far as workflow, we can just do either as it's not a requirement (note that we are not working directly on a devuan.org branch).

    @mmaglis Since your branch already exists you can use "git checkout el" instead. The -b flag will cause the branch to be created when it's not there. So in this case you don't need the -b flag. Use 'git branch' to see all branches. I will add this when updating the guide.

    When I catch up in the master branch I'll create this guide in contributing.md instead as people familiar with git may look for that.

    Edited by dev1fanboy
  • dev1fanboy @dev1fanboy mentioned in issue #82 (closed) ·

    mentioned in issue #82 (closed)

  • Linuxito
    Linuxito @linuxito ·

    Excellent! Thank you @dev1fanboy

  • dev1fanboy @dev1fanboy mentioned in issue #112 (closed) ·

    mentioned in issue #112 (closed)

  • Douglas
    Douglas @crimson_king ·

    I'm not being able to checkout to the pt branch.

    EDIT: Nevermind, after some searching I've found the proper way of doing this:git checkout -b pt origin/pt 

    * master
  remotes/origin/HEAD -> origin/master
  remotes/origin/de
  remotes/origin/development
  remotes/origin/el
  remotes/origin/es
  remotes/origin/it
  remotes/origin/it-in-folder
  remotes/origin/it-updated
  remotes/origin/master
  remotes/origin/pl
  remotes/origin/pt

    So, Icdinto Upgrade-Install-Devuan/pt and run git checkout pt, but it returnserror: pathspec 'pt' did not match any file(s) known to git.

    I triedgit checkout ptfrom Upgrade-Install-Devuan instead. It prints nothing back to me;git branch -ashows that I'm still on master. How do you do it?

    I keep changing my operating system all the time. This time I decided to try Trisquel, and now I got stuck here. Trisquel 8 is based on Ubuntu 16.04. Perhaps this old version of git works differently.

    Edited by Douglas
  • dev1fanboy
    dev1fanboy @dev1fanboy ·

    @crimson_king

    Sorry for the delay getting back to you.

    You should really run git checkout pt in the Upgrade-Install-Devuan directory, since git keeps that information in the root (parent) directory.

    I checked myself and found the situation is the same. Your edit with the solution worked to fix that issue. I don't remember having to do this but apparently it's how to do it now.

    Edited by dev1fanboy