More extensive documentation on setting up SVN/git-based L10n.

docs/l10n_setup.rst

@@ -3,8 +3,8 @@ L10n Setup
 
 So you'd like to localize your webapp. **Congratulations!**
 
-Playdoh comes with all of the libraries and tools you need
-in the dev and production requirements.
+Playdoh comes with all of the libraries and tools you need in the dev and
+production requirements.
 
 Requirements
 ------------
@@ -13,29 +13,93 @@ The one set of low level tools not provided is gettext.
 
 ::
 
-    aptitutde install gettext
+    aptitude install gettext
+    # or
+    brew install gettext
 
 Steps
 -----
 
+To allow localizers to translate your app on localize.mozilla.org, your .po
+files need to be in SVN. To play nice with our git-based application code,
+we need to keep this SVN repository in sync with a git repository.
+
 The following steps will get you started:
 
-#. Create a SVN reposity with directories based on MDN_ 
-   locale directory. Playdoh comes with bin/complie-mo.sh   
-#. Compile the po files and mirror the SVN repository in a 
-   git repository via a cron job that runs every 15 minutes. 
-   Example: (TBD)
-   /home/fwenzel/bin/autol10n/autol10n.sh
-#. Add your git repo as an external to this project
-   It should create a locale directory at the top level 
-#. Read the next section L10n udpate for a better understanding of
-   what Django management commands are used to extract and
-   merge strings into your po files. It has instructions
-   for adding more locales.
+#.  Create an SVN repository with directories based on MDN_ locale directory.
+    You need at least::
+
+        ./en_US
+        ./en_US/LC_MESSAGES
+        ./templates
+        ./templates/LC_MESSAGES
+
+#.  Make a new git repository (a convention is to call it ``myproject-locale``),
+    and clone the SVN repo into it. ::
+
+        cd /my/playdoh/project/dir/
+        git svn clone https://svn.mozilla.org/projects/something/trunk/locale locale
+        cd locale
+        git add remote origin git@github.com:mozilla/myproject-locale.git
+        git push origin master
+        cd ..
+
+    Now extract strings from your project::
+
+        ./manage.py extract
+        ./manage.py verbatimize --rename
+        ./manage.py merge
+
+#.  Commit it all locally
+#.  Build your .mo files and commit those as well::
+
+        ./bin/compile-mo.sh locale/
+        cd locale
+        git add .
+        git commit -m 'Built .mo files'
+
+#.  Finally push this to SVN followed by a push to git. ::
+
+        git svn dcommit && git push origin HEAD
+
+    **A note on SVN vs. git:** When you ``git svn dcommit``, git will add
+    SVN metadata to your git commit message. This causes the *commit ID to
+    change*. So you always want to push to SVN first, then to git, not
+    vice versa, or git will be a sad panda because your local and remote
+    histories diverge.
+
+#.  Add the ``locale/`` directory as a *git submodule* to your main code
+    repository, so that they can be deployed together::
+
+        git submodule add git://github.com/mozilla/myproject-locale.git locale
+        # (commit, push)
+    
+
+Advanced Steps
+--------------
+
+#.  localize.mozilla.org does not automatically compile .mo files when a
+    localizer commits to SVN. Neither does it automate the push over to
+    git. There's a handy little script called ``autol10n`` that you can
+    run as a cron job somewhere, which will:
+    
+    * pick up changed .po files from SVN,
+    * compile the .mo files,
+    * then push everything over to git...
+    * ... and retag the git submodule to the latest revision.
+
+    The script is available in playdoh under ``bin/autol10n.sh``.
+
+#.  Read the next section (:ref:`l10n-update`) for a better understanding of
+    what Django management commands are used to extract and merge strings into
+    your po files. It has instructions for adding more locales.
+
+.. _MDN: http://svn.mozilla.org/projects/mdn/trunk/locale/
 
 Q&A
 ---
-Why SVN? Our localizers like to use either SVN or Verbatim.
-Why a git repo to mirror an SVN repo? This allows us to have an external reference and update easily.
 
-.. _MDN: http://svn.mozilla.org/projects/mdn/trunk/locale/
+* *Why SVN?* Our localizers like to use either SVN or Verbatim.
+* *Why a git repo to mirror an SVN repo?* This allows us to have an external
+  reference ("git submodule") and deploy the app including its translations
+  easily.

docs/l10n_update.rst

@@ -1,7 +1,9 @@
+.. _l10n-update:
+
 L10n Update
 ===========
 
-Follow these steps to update strings for L10n.
+Follow these steps to **update** strings for L10n.
 
 We are using English strings for gettext message ids.
 
@@ -19,25 +21,33 @@ files and lastly commiting to SVN.
 Instructions:
 -------------
 
-1. ``./manage.py extract ``
-2. ``./manage.py verbatimize --rename``
-   This will copy the POT files created in step 1 to templates/LC_MESSAGES
-3. ``./manage.py merge``
+::
+
+    ./manage.py extract
+
+    ./manage.py verbatimize --rename
+    # This will copy the POT files created in step 1 to templates/LC_MESSAGES.
+
+    ./manage.py merge
+
 
 Optional:
 ---------
 
-4. ``locale/compile-mo.sh locale``
+To compile all .mo files::
+
+    ./bin/compile-mo.sh locale/
+
 
 New Locales:
 ------------
 
 Assuming you want to add 'fr':
 
-#. ``mkdir -p locale/fr/LC_MESSAGES``
-#. ``./manage.py merge``
+#.  ``mkdir -p locale/fr/LC_MESSAGES``
+#.  ``./manage.py merge``
 
 or
 
-#. ``msginit --no-translator -l fr -i templates/LC_MESSAGES/messages.pot -o fr/LC_MESSAGES/messages.po``
-#. repeat for other POT files
+#.  ``msginit --no-translator -l fr -i templates/LC_MESSAGES/messages.pot -o fr/LC_MESSAGES/messages.po``
+#.  repeat for other POT files