Skip to content

Commit

Permalink
add explanation to README and format guides carpentries-i18n#5 carpen…
Browse files Browse the repository at this point in the history 
…tries-i18n#6 carpentries-i18n#8 carpentries-i18n#11 carpentries-i18n#12 carpentries-i18n#14
  • Loading branch information
@TomKellyGenetics
TomKellyGenetics committed Nov 10, 2018
1 parent f364cda commit db8583c
Showing 1 changed file with 263 additions and 8 deletions.
271 changes: 263 additions & 8 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,257 @@
# Internationalisation of carpentry lessons

## Purpose of this repository

The repository is intended to host the files and tools need to facilitate translations of the Software Carpentry lessons
from English into other languages. This repository is intended to merge with the Multi-lingual versions of the lessons
in English and Spanish. We plan for these to be compatible to be hosted along with other languages on the main
Software Carpentry website and to maintain updated copies of the Japanese lessons with new releases of the
English lessons. Therefore:

* Please do not remove the files for other languages (currently Spanish) from the repository.
These need to be retained to merge the lessons with the main i18n repository and existing lessons.

* Please do not delete the archived files for translation of previous versions of the English lessons.
These will be needed to merge translations with updated English files for future releases of the
main Software Carpentry lessons. This means that we will only need to translate updated sections and
translations to sections that have not been updated will be migrated to new releases.

* Please only submit changes specific to Japanese language translations to this repository as Pull Requests.
Please submit issues specific to the English lessons to the main lesson repository. If you have a suggestion
for a change to the content or examples, we cannot change these in the Japanese lesson and the main lessons
need to be updated in English. We ask that these changes be raised as an Issue in Japanese rather than a
Pull Request if you prefer not to submit an Issue or Pull Request in English.

* Please contact us if you wish to join the core translation team. Any contributions to the Japanese lessons
are welcome as Pull Requests but please make sure you understand the English version of the lesson if
you are able to.

* Please commit and push changes to a fork of the reposiory on your personal GitHub account and
submit a Pull Request. In this way, suggested changes can be reviewed and discussed. Please raise
any matters that you are unsure of or want help with when submitting a Pull Request.

* Please track changes to all files needed to generate the translated lessons. This way we can combine
all changes from contributors and track our progress. All contributions will be attributed to each
contributor.

* Please contact us via an Issue if anything is unclear in the guides to set up or use the
translation tools in this repository so we can update the README and guides.

## How does this work?

1. Add a submodule for the lessons that you want to translate
2. Run `po4gitbook/update.sh` - That creates/updates the `po` directory with the `.pot` files to use in translations.
3. First time for this lesson: `cp git-novice.pot .git-novice.po.ancestor` Please **do not delete** these files.
### Importing a lesson for the first time

If you wish to start a translation of a lesson that has not been translated in your language before,
please follow these instructions. See the instructions below for if your lesson has an exisiting
translation and you wish to submit changes or an update.

1. Create a "Fork" for this repository on your personal GitHub account. (Click "Fork" in the top right
corner of the `https://github.com/swcarpentry-ja/i18n` webpage)

2. Clone this repository from your personal account (e.g., GitHubUser). This is your local copy to manage your version of
the translation files.

```
cd directory
git clone [email protected]:GitHubUser/i18n.git
cd i18n
```

If you already have a fork of translation repository, please pull changes for the current
version from the organisation repository:

```
git checkout ja
git remote add swc-ja [email protected]:swcarpentry-ja/i18n.git
git pull swc-ja ja
```


3. Add a submodule for the lessons that you want to translate

```
git submodule add https://github.com/swcarpentry/git-novice.git
```

4. Run `po4gitbook/update.sh` - That creates/updates the `po` directory with the `.pot` files to use in translations.

5. Archive a copy of the raw pot files.

3. For an update: merge existing translations into updated file
```bash
git merge-file git-novice.pot .git-novice.pot.ancestor git-novice.ja.po
```
4. Create a `po` file and start translating!
cd po
cp git-novice.pot .git-novice.po.ancestor
git add .git-novice.po.ancestor
git commit -m "archive ancestor file for git-novice lesson"
```

Please **do not delete** these files.

6. Create a `po` file and start translating!
- copy `<file>.pot` to `<file>.<lang>.po`. e.g.,
```bash
cd po
cp shell-novice.pot shell-novice.es.po
```
- Edit the file with your favourite po editor ([PoEdit](http://www.poedit.net),
[GTranslator](https://wiki.gnome.org/Apps/Gtranslator), [Lokalize](https://userbase.kde.org/Lokalize), ...)
Note:
- "`Language`" field is needed to add to the header (at least with gtranslator), the rest is put by the tool.
- "`Language-Team:`" needs the first letter in upper case (e.g., `Es` or `Ja`)
- Create `po/LINGUAS`
- run `po4gitbook/compile.sh` - This creates a `locale/<lang>/<lesson>` tree directory

This generates a translated version of the lessons. Please do not create a git repository within
this repository. You can copy these files to another repository as described in the
"Guide for Translators" and submit changes to the PO files via Pull Request to GitHub.

Please note that there are files shared between lesson repositories:
```
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE.md
README.md
```
These will be hosted on the translated Git repository but will not be included in the
webpages once they are generated. Apart from the `README`, these are the same files
between each lesson. Please check that these files have not been already translated
for another lesson. If so you can copy these to ensure they are consistent.

While these files appear at the beginning of the PO files (since files are sorted alphabetically),
they are not a priority to translate. Please skip to the beginning of the lesson,
following the README.

### Contributing to a translation of an existing lesson

Please see these instructions if you wish to contribute to a translation in progress
on the current version the main English lessons. This is for updating or translating
sections to a translation in progress. To import updates from a new release of
the main English lessons, please see the instructions below.

1. Create a "Fork" for this repository on your personal GitHub account. (Click "Fork" in the top right
corner of the `https://github.com/swcarpentry-ja/i18n` webpage)

2. Clone this repository from your personal account (e.g., GitHubUser). This is your local copy to manage your version of
the translation files.

```
cd directory
git clone [email protected]:GitHubUser/i18n.git
cd i18n
```

If you already have a fork of translation repository, please pull changes for the current
version from the organisation repository:

```
git checkout ja
git remote add swc-ja [email protected]:swcarpentry-ja/i18n.git
git pull swc-ja ja
```

This repository should already contain a translation file for the lesson that you wish to contribute to
in the `po` directory <lesson-name>.<lang>.po such as `git-novice.ja.po`

```bash
cd po
ls git-novice.ja.po
```

3.
- Edit the file with your favourite po editor ([PoEdit](http://www.poedit.net),
[GTranslator](https://wiki.gnome.org/Apps/Gtranslator), [Lokalize](https://userbase.kde.org/Lokalize), ...)
Note:
- "`Language`" field is needed to add to the header (at least with gtranslator), the rest is put by the tool.
- "`Language-Team:`" needs the first letter in upper case (e.g., `Es`)
- Create `po/LINGUAS`
- Run `po4gitbook/compile.sh` - This creates a `locale/<lang>/<lesson>` tree directory

This generates a translated version of the lessons with your changes. You can add and commit
changes to the PO files and submit changes as a Pull Request on GitHub as described in the
"Guide for Translators".

Please do not create a git repository within this repository. You can copy these files to another repository
as described in the "Guide for Maintainers and Administrators" and submit changes to translated
lesson repository to update the webpages hosted on GitHub.

### Contributing to translation of an updated lesson with a new release of the main English lessons

If there is an existing (complete) translation of the lesson in your language but
there has a new release of the main English lessons, the new updated version
of the English lessons needs to be merged with the current translated. This way
the sections have not been changed and have already been translated will be migrated
to the new version of the lessons and only the sections that have been changed remain
to be translated.

1. Create a "Fork" for this repository on your personal GitHub account. (Click "Fork" in the top right
corner of the `https://github.com/swcarpentry-ja/i18n` webpage)

2. Clone this repository from your personal account (e.g., GitHubUser). This is your local copy to manage your version of
the translation files.

```
cd directory
git clone [email protected]:GitHubUser/i18n.git
cd i18n
```

If you already have a fork of translation repository, please pull changes for the current
version from the organisation repository:

```
git checkout ja
git remote add swc-ja [email protected]:swcarpentry-ja/i18n.git
git pull swc-ja ja
```

3. Check the previous (untranslated PO files) lesson is archived.

Please check the PO file for the originally translated English lesson exists (from before translations).
It should be names in the format `.<lesson-name>.<lang>.po.ancestor`

```
ls -a .git-novice.po.ancestor
```

- Archive previous version.
If it does not exist. You need to create a blank version of the PO file for the previous version
of the lesson **BEFORE** updating the submodule for the new version of the lesson.
- Run `po4gitbook/update.sh` - That creates/updates the `po` directory with the `.pot` files to use in translations.
- Archive a copy of the raw pot files.

```
cd po
cp git-novice.pot .git-novice.po.ancestor
git add .git-novice.po.ancestor
git commit -m "archive ancestor file for git-novice lesson"
cd ..
```

4. Import the current version of the main English lessons.

Update the submodule for the lesson that you want to translate

```
git submodule add https://github.com/swcarpentry/git-novice.git
```

Alternatively, you can update the submodules for every lesson:

```
git submodule foreach git pull origin master
```

5. Create translation files for the updated version of the lessons

Run `po4gitbook/update.sh` - That creates/updates the `po` directory with the `.pot` files to use in translations.

For an update: merge existing translations into updated file.
```bash
cd po
cp shell-novice.pot shell-novice.es.po
git merge-file git-novice.pot .git-novice.pot.ancestor git-novice.ja.po
```

5. This creates an updated `po` file with updated sections ready to translate.

```
- Edit the file with your favourite po editor ([PoEdit](http://www.poedit.net),
[GTranslator](https://wiki.gnome.org/Apps/Gtranslator), [Lokalize](https://userbase.kde.org/Lokalize), ...)
Expand All @@ -25,6 +261,14 @@ cp shell-novice.pot shell-novice.es.po
- Create `po/LINGUAS`
- Run `po4gitbook/compile.sh` - This creates a `locale/<lang>/<lesson>` tree directory
This generates a translated version of the lessons with your changes. You can add and commit
changes to the PO files and submit changes as a Pull Request on GitHub as described in the
"Guide for Translators".
Please do not create a git repository within this repository. You can copy these files to another repository
as described in the "Guide for Maintainers and Administrators" and submit changes to translated
lesson repository to update the webpages hosted on GitHub.
## Guide for Translators
This assumes that you are familiar with using Git and GitHub.
Expand Down Expand Up @@ -71,8 +315,19 @@ ChangeLog.md is to track progress and goals. CultureNotes.md is a share record o
Thank you for all your help. Even seemingly minor contributions will be appreciated!
## Guide for Maintainers and Administrators
### To update the GitHub pages lessons with Jekyll
This assumes a high level of familiarity with Git, GitHub, and how these lessons have been configured. These tools can be used to
update the webpages hosted on the organisation repository or create a hosted webpage on your personal fork.
Updates to the files can be managed by tracking changes to the PO files and translated lessons
can be viewed on the GitHub repository as Markdown files in the `_episodes` directory
of the respectve lesson repo. It is not necessary to update the webpages for every update to
the translations. This will be managed by lesson maintainers and organisers of the Japanese
language team.
1. Run `po4gitbook/compile.sh` on updated PO files (commit and push changes to PO files to i18n)
Note that in order for the lessons to compile the Credit line in the PO files HEADER
Expand Down

0 comments on commit db8583c

Please sign in to comment.