Sphinx and transifex config for translations

.gitignore

@@ -5,3 +5,4 @@ node_modules
 *~
 *.swp
 *.pytest_cache*
+*.mo

.tx/config

@@ -0,0 +1,225 @@
+[main]
+host = https://www.transifex.com
+
+[bods-v01.privacy-notice]
+file_filter = docs/locale/<lang>/LC_MESSAGES/privacy-notice.po
+source_file = docs/_build/gettext/privacy-notice.pot
+source_lang = en
+type = PO
+
+[bods-v01.usecases]
+file_filter = docs/locale/<lang>/LC_MESSAGES/usecases.po
+source_file = docs/_build/gettext/usecases.pot
+source_lang = en
+type = PO
+
+[bods-v01.index]
+file_filter = docs/locale/<lang>/LC_MESSAGES/index.po
+source_file = docs/_build/gettext/index.pot
+source_lang = en
+type = PO
+
+[bods-v01.about--governance]
+file_filter = docs/locale/<lang>/LC_MESSAGES/about/governance.po
+source_file = docs/_build/gettext/about/governance.pot
+source_lang = en
+type = PO
+
+[bods-v01.about--credits]
+file_filter = docs/locale/<lang>/LC_MESSAGES/about/credits.po
+source_file = docs/_build/gettext/about/credits.pot
+source_lang = en
+type = PO
+
+[bods-v01.about--index]
+file_filter = docs/locale/<lang>/LC_MESSAGES/about/index.po
+source_file = docs/_build/gettext/about/index.pot
+source_lang = en
+type = PO
+
+[bods-v01.about--support]
+file_filter = docs/locale/<lang>/LC_MESSAGES/about/support.po
+source_file = docs/_build/gettext/about/support.pot
+source_lang = en
+type = PO
+
+[bods-v01.userguides--validating-and-verifying]
+file_filter = docs/locale/<lang>/LC_MESSAGES/userguides/validating-and-verifying.po
+source_file = docs/_build/gettext/userguides/validating-and-verifying.pot
+source_lang = en
+type = PO
+
+[bods-v01.userguides--updating-data]
+file_filter = docs/locale/<lang>/LC_MESSAGES/userguides/updating-data.po
+source_file = docs/_build/gettext/userguides/updating-data.pot
+source_lang = en
+type = PO
+
+[bods-v01.userguides--publishing-ben-ownership-data]
+file_filter = docs/locale/<lang>/LC_MESSAGES/userguides/publishing-ben-ownership-data.po
+source_file = docs/_build/gettext/userguides/publishing-ben-ownership-data.pot
+source_lang = en
+type = PO
+
+[bods-v01.userguides--using-ben-ownership-data]
+file_filter = docs/locale/<lang>/LC_MESSAGES/userguides/using-ben-ownership-data.po
+source_file = docs/_build/gettext/userguides/using-ben-ownership-data.pot
+source_lang = en
+type = PO
+
+[bods-v01.userguides--index]
+file_filter = docs/locale/<lang>/LC_MESSAGES/userguides/index.po
+source_file = docs/_build/gettext/userguides/index.pot
+source_lang = en
+type = PO
+
+[bods-v01.userguides--links-other-standards]
+file_filter = docs/locale/<lang>/LC_MESSAGES/userguides/links-other-standards.po
+source_file = docs/_build/gettext/userguides/links-other-standards.pot
+source_lang = en
+type = PO
+
+[bods-v01.userguides--bulk-data-and-api]
+file_filter = docs/locale/<lang>/LC_MESSAGES/userguides/bulk-data-and-api.po
+source_file = docs/_build/gettext/userguides/bulk-data-and-api.pot
+source_lang = en
+type = PO
+
+[bods-v01.userguides--licensing]
+file_filter = docs/locale/<lang>/LC_MESSAGES/userguides/licensing.po
+source_file = docs/_build/gettext/userguides/licensing.pot
+source_lang = en
+type = PO
+
+[bods-v01.toolbox--index]
+file_filter = docs/locale/<lang>/LC_MESSAGES/toolbox/index.po
+source_file = docs/_build/gettext/toolbox/index.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--reference]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/reference.po
+source_file = docs/_build/gettext/schema/reference.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--conformance]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/conformance.po
+source_file = docs/_build/gettext/schema/conformance.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--schema-browser]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/schema-browser.po
+source_file = docs/_build/gettext/schema/schema-browser.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--index]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/index.po
+source_file = docs/_build/gettext/schema/index.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--changelog]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/changelog.po
+source_file = docs/_build/gettext/schema/changelog.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--concepts]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/concepts.po
+source_file = docs/_build/gettext/schema/concepts.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--guidance--identifiers]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/guidance/identifiers.po
+source_file = docs/_build/gettext/schema/guidance/identifiers.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--guidance--updating-data]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/guidance/updating-data.po
+source_file = docs/_build/gettext/schema/guidance/updating-data.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--guidance--provenance]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/guidance/provenance.po
+source_file = docs/_build/gettext/schema/guidance/provenance.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--guidance--functional-requirements]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/guidance/functional-requirements.po
+source_file = docs/_build/gettext/schema/guidance/functional-requirements.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--guidance--index]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/guidance/index.po
+source_file = docs/_build/gettext/schema/guidance/index.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--guidance--languages]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/guidance/languages.po
+source_file = docs/_build/gettext/schema/guidance/languages.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--guidance--statement-identifiers]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/guidance/statement-identifiers.po
+source_file = docs/_build/gettext/schema/guidance/statement-identifiers.pot
+source_lang = en
+type = PO
+
+[bods-v01.schema--guidance--serialization]
+file_filter = docs/locale/<lang>/LC_MESSAGES/schema/guidance/serialization.po
+source_file = docs/_build/gettext/schema/guidance/serialization.pot
+source_lang = en
+type = PO
+
+[bods-v01.examples--index]
+file_filter = docs/locale/<lang>/LC_MESSAGES/examples/index.po
+source_file = docs/_build/gettext/examples/index.pot
+source_lang = en
+type = PO
+
+[bods-v01.primer--whyisbo]
+file_filter = docs/locale/<lang>/LC_MESSAGES/primer/whyisbo.po
+source_file = docs/_build/gettext/primer/whyisbo.pot
+source_lang = en
+type = PO
+
+[bods-v01.primer--index]
+file_filter = docs/locale/<lang>/LC_MESSAGES/primer/index.po
+source_file = docs/_build/gettext/primer/index.pot
+source_lang = en
+type = PO
+
+[bods-v01.primer--whatisbo]
+file_filter = docs/locale/<lang>/LC_MESSAGES/primer/whatisbo.po
+source_file = docs/_build/gettext/primer/whatisbo.pot
+source_lang = en
+type = PO
+
+[bods-v01.primer--whatisthebods]
+file_filter = docs/locale/<lang>/LC_MESSAGES/primer/whatisthebods.po
+source_file = docs/_build/gettext/primer/whatisthebods.pot
+source_lang = en
+type = PO
+
+[bods-v01.primer--whatisbodata]
+file_filter = docs/locale/<lang>/LC_MESSAGES/primer/whatisbodata.po
+source_file = docs/_build/gettext/primer/whatisbodata.pot
+source_lang = en
+type = PO
+
+[bods-v01.primer--whatdoesbodscover]
+file_filter = docs/locale/<lang>/LC_MESSAGES/primer/whatdoesbodscover.po
+source_file = docs/_build/gettext/primer/whatdoesbodscover.pot
+source_lang = en
+type = PO
+

README.md

@@ -26,3 +26,33 @@ The initial development of the Beneficial Ownership Data Standard is funded thro
 ### Build the docs locally
 
 Please see https://github.com/openownership/data-standard-sphinx-theme
+
+### Translation
+
+Translation consists of generating strings to be translated from the English docs, pushing them to Transifex, fetching translations back from Transifex, and then you can build the docs in the other languages you need.
+
+To run the steps in the translation workflow, you need to install this repo and its dependencies in your local environment.
+
+```
+$ pip install -r requirements.txt 
+```
+
+And you need to get a [Transifex API key](https://www.transifex.com/user/settings/api/), make sure you have access to the [BODS project on Transifex](https://www.transifex.com/OpenDataServices/bods-v01)
+
+**When you add or update the docs** you need to do the following so that they can be translated, in the `docs` directory:
+
+1. Run `make gettext` to extract translatable English strings.
+2. *If you have new pages* run `sphinx-intl update-txconfig-resources --pot-dir _build/gettext --transifex-project-name bods-v01` to register the translation files with Transifex (generates or updates contents `.tx/config` file).
+3. Run `tx push -s` to push to Transifex.
+
+Now the files are ready to be translated in Transifex.
+
+**To fetch new translations** when they're done, you need to:
+
+1. Run `tx pull -a` to fetch all, or `tx pull -l ru` to fetch a particular language.
+
+**To build another language locally** use `make html` (in the `docs` directory) but pass the language you want:
+
+```
+$ sphinx-build -b html -D language=ru . _build/html/ru
+```

docs/conf.py

@@ -16,9 +16,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
+import os
 from recommonmark.transform import AutoStructify
 from recommonmark.parser import CommonMarkParser
 
@@ -67,13 +67,6 @@
 # The full version, including alpha/beta/rc tags.
 release = '0.1'
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
@@ -113,6 +106,16 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'BODS'
 
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+locale_dirs = ['locale/', os.path.join(oods.sphinxtheme.get_html_theme_path(), 'locale')]
+gettext_compact = False
+gettext_uuid = True
+
 
 # -- Options for LaTeX output ---------------------------------------------
 

docs/locale/es/LC_MESSAGES/about/credits.po

@@ -0,0 +1,41 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2017, OpenOwnership
+# This file is distributed under the same license as the Beneficial Ownership Data Standard package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+# 
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: Beneficial Ownership Data Standard 0.1\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2019-01-31 15:20+0000\n"
+"PO-Revision-Date: 2019-01-31 16:16+0000\n"
+"Language-Team: Spanish (https://www.transifex.com/OpenDataServices/teams/95583/es/)\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Language: es\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+
+# 2ecce5a2c01b4f9487c0a3492e13f43a
+#: ../../about/credits.md:1
+msgid "Credits"
+msgstr ""
+
+# 675ee2e810064612befeeeeb0217a7e8
+#: ../../about/credits.md:4
+msgid ""
+"The first beta version of the Beneficial Ownership Data Standard was written"
+" by Tim Davies (Open Data Services Co-operative) with Ben Symonds "
+"(OpenCorporates), Chris Taggart (OpenCorporates) and Jack Lord (Open Data "
+"Services Co-operative) and supported by the data standard working group."
+msgstr ""
+
+# 9773c6249b444e7fae24be716c29e236
+#: ../../about/credits.md:6
+msgid ""
+"The 0.1 version was written by Tim Davies and Jack Lord with supporting "
+"documentation from Kadie Armstrong (Open Data Services Co-operative), "
+"technical work from James Baster (Open Data Services Co-operative) and input"
+" from the data standard working group."
+msgstr ""