add explanation to README and format guides #5 #6 #8 #11 #12 #14

swcarpentry-ja · Nov 10, 2018 · db8583c · db8583c
1 parent f364cda
commit db8583c
Showing 1 changed file with 263 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -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), ...)
@@ -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.
@@ -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