DOCS-775: refactor, organization, and edits

Author: Sam Kleinman

conf.py

@@ -77,6 +77,27 @@
         'djangotoolbox' : ('http://djangotoolbox.readthedocs.org/en/latest/', '../build/djangotoolbox.inv'),
 }
 
+languages = [
+    ("ar", "Arabic"),
+    ("cn", "Chinese"), 
+    ("cs", "Czech"), 
+    ("de", "German"),
+    ("es", "Spanish"),
+    ("fr", "French"), 
+    ("hu", "Hungarian"),  
+    ("id", "Indonesian"),  
+    ("it", "Italian"),  
+    ("jp", "Japanese"), 
+    ("ko", "Korean"),  
+    ("lt", "Lithuanian"), 
+    ("pl", "Polish"),  
+    ("pt", "Portuguese"), 
+    ("ro", "Romanian"),  
+    ("ru", "Russian"),  
+    ("tr", "Turkish"),
+    ("uk", "Ukrainian")
+]
+
 # -- Options for HTML output ---------------------------------------------------
 
 html_theme = 'mongodb'
@@ -103,15 +124,19 @@
     'pdfpath': manual_edition_path + '.pdf',
     'epubpath': manual_edition_path + '.epub',
     'manual_path': meta['manual_path'],
+    'translations': languages,
     'repo_name': 'docs',
     'jira_project': 'DOCS',
     'google_analytics': 'UA-7301842-8',
     'project': 'manual',
 }
 
 html_sidebars = {
-    '**': ['pagenav.html', 'formats.html', 'translations.html', 'wikisidebar.html'],
+    '**': ['pagenav.html'],
 }
+html_sidebars['**'].append('formats.html')
+# html_sidebars['**'].append('translations.html')
+html_sidebars['**'].append('wikisidebar.html')
 
 # -- Options for LaTeX output --------------------------------------------------
 

source/about.txt

@@ -104,6 +104,14 @@ always available at "http://docs.mongodb.org/manual/."
 Contributing to the Documentation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. this toctree should be moved to a not-yet-extant "translation"
+   section of this page.
+
+.. toctree:: 
+   :hidden: 
+
+   /meta/translation
+
 The entire source of the documentation is available in the `docs
 repository <https://github.com/mongodb/docs>`_ along with all of the
 other `MongoDB project repositories on GitHub <http://github.com/mongodb>`_.

source/i18n.txt renamed to source/meta/translation.txt

@@ -1,41 +1,46 @@
-.. this file is hardlinked from translations.html in themes/mongodb
 .. _internationalization:
 
 ===================================================
 MongoDB Manual Internationalization and Translation
 ===================================================
+
 .. default-domain:: mongodb
 
-The primary language of the MongoDB Documentation is English
-(American English at that) but we recognize the need to provide
-documentation in additional languages.
+The original authorship language for all MongoDB documentation is
+American English. However, ensuring that speakers of other languages
+can read and understand the documentation is of critical importance to
+the documentation project.
+
+In this direction, the MongoDB Documentation project uses the service
+provided by `Smartling <http://smartling.com/>`_ to translate the
+MongoDB documentation into additional non-English languages. This
+translation project is largely supported by the work of volunteer
+translators from the MongoDB community who contribute to the
+translation effort.
 
-We are using a service provided by `Smartling <http://smartling.com/>`_
-to translate the MongoDB documentation into additional languages.
+If you would like to volunteer to help translate the MongoDB
+documentation, please:
 
-If you would like to volunteer to translate the MongoDB documentation,
-we need you to complete the
-`10gen/MongoDB Contributor Agreement <http://www.10gen.com/legal/contributor-agreement>`_.
-You will also need to create an account on Smartling at
+- complete the `10gen/MongoDB Contributor Agreement
+  <http://www.10gen.com/legal/contributor-agreement>`_, and
+- create an account on Smartling at
 `translate.docs.mongodb.org <http://translate.docs.mongodb.org/>`_.
 
-Please use the same email address you use to ``sign`` the Contributor
-agreement when you create the Smartling account.
+Please use the same email address you use to sign the contributor as
+you use to create your Smartling account.
 
-We have a Google Group for translators at
-`mongodb-translators <http://groups.google.com/group/mongodb-translators>`_
-You can join the Google Group w/o signing the contributor's agreement
-but we will need a signed agreement before I add you to the Smartling
-project.
+The `mongodb-translators`_ user group exists to facilitate
+collaboration between translators and the documentation team at large.
+You can join the Google Group without signing the contributor's
+agreement.
 
 We currently have the following languages configured:
 
 - `Arabic <http://ar.docs.mongodb.org>`_
 - `Chinese <http://cn.docs.mongodb.org>`_
 - `Czech <http://cs.docs.mongodb.org>`_
-- `German <http://de.docs.mongodb.org>`_
-- `Spanish <http://es.docs.mongodb.org>`_
 - `French <http://fr.docs.mongodb.org>`_
+- `German <http://de.docs.mongodb.org>`_
 - `Hungarian <http://hu.docs.mongodb.org>`_
 - `Indonesian <http://id.docs.mongodb.org>`_
 - `Italian <http://it.docs.mongodb.org>`_
@@ -46,16 +51,20 @@ We currently have the following languages configured:
 - `Portuguese <http://pt.docs.mongodb.org>`_
 - `Romanian <http://ro.docs.mongodb.org>`_
 - `Russian <http://ru.docs.mongodb.org>`_
+- `Spanish <http://es.docs.mongodb.org>`_
 - `Turkish <http://tr.docs.mongodb.org>`_
 - `Ukrainian <http://uk.docs.mongodb.org>`_
 
-If we are missing your language please contact us (through the
-``Report a Problem`` link above or by posting to ``mongodb-translators``).
+If you would like to initiate a translation project to an additional
+language, please report this issue using the "*Report a Problem*" link
+above or by posting to the `mongodb-translators`_ list.
 
-While the translation effort is currently focused on the web site we are
+Currently the translation project only publishes rendered translation While the translation effort is currently focused on the web site we are
 evaluating how to retrieve the translated phrases for use in other
 media.
 
+.. _`mongodb-translators`: http://groups.google.com/group/mongodb-translators
+
 .. seealso::
 
    - :ref:`meta-contributing`

themes/mongodb/theme.conf

@@ -11,4 +11,5 @@ manual_path = PATH
 repo_name = REPONAME
 jira_project = JIRA
 google_analytics = GACODE
-project = PROJECT
+project = PROJECT
+translations = LANGUAGES

themes/mongodb/translations.html

@@ -1,48 +1,22 @@
-{# This is one pass at adding national language links to pages but I'm concerned
-   it is making build take significantly longer.  It really shouldn't. But perhaps
-   hardlinks to the languages and a JS thing to click to "this page in Klingon"?
-#}
-{%- set nlslangs = {
-   "ar": "Arabic",
-   "cn": "Chinese",
-   "cs": "Czech",
-   "de": "German",
-   "es": "Spanish",
-   "fr": "French",
-   "hu": "Hungarian",
-   "id": "Indonesian",
-   "it": "Italian",
-   "jp": "Japanese",
-   "ko": "Korean",
-   "lt": "Lithuanian",
-   "pl": "Polish",
-   "pt": "Portuguese",
-   "ro": "Romanian",
-   "ru": "Russian",
-   "tr": "Turkish",
-   "uk": "Ukrainian"
-   }
--%}
-<h3>Translations</h3>
-<p><a href="//docs.mongodb.org/manual/i18n/">About the translation project</a></p>
-<ul class="translation-menu">
-{% set domain = 'docs.mongodb.org' %}
 {%- if pagename == "index" %}
-{% set temppagename = "" %}
+   {% set page_path = "" %}
 {% elif file_suffix == '' %}
-{% set tempagename = pagename + "/" %}
+   {% set tempagename = pagename + "/" %}
 {% else %}
-{% set temppagename = pagename %}
+   {% set page_path = pagename %}
 {% endif %}
+
 {%- if theme_project == 'manual' %}
-{% set pageuri = theme_manual_path + "/" + temppagename %}
+   {% set page_uri = theme_manual_path + "/" + page_path %}
 {%- elif theme_project == 'ecosystem' %}
-{% set pageuri = theme_project + "/" + temppagename %}
+   {% set page_uri = theme_project + "/" + page_path %}
 {%- elif theme_project == 'meta-driver' %}
-{% set pageuri = theme_project + "/" + theme_manual_path + "/" + temppagename %}
+   {% set page_uri = theme_project + "/" + theme_manual_path + "/" + page_path %}
 {%- endif %}
-{%- for lc,lang in nlslangs|dictsort(true): -%}
-{%- set lang = nlslangs[lc] -%}
-<li><a href="http://{{lc}}.{{domain}}/{{pageuri}}" rel="nofollow" hreflang="{{lc}}" title="{{html_short_title}} in {{lang}}">{{lang}}</a></li>
+
+<h3><a href="{{ pathto('/meta/translation') }}">Translations</a></h3>
+<ul class="translation-menu">
+{%- for lc,lang in theme_translations -%}
+    <li><a href="http://{{lc}}.docs.mongodb.org/{{ page_url }}" rel="nofollow" hreflang="{{lc}}" title="{{html_short_title}} in {{lang}}">{{lang}}</a></li>
 {% endfor -%}
 </ul>