diff --git a/bin/docstheme-build-translated.sh b/bin/docstheme-build-translated.sh new file mode 100755 index 0000000..e3d7e8c --- /dev/null +++ b/bin/docstheme-build-translated.sh @@ -0,0 +1,167 @@ +#!/bin/bash + +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +# Build English and translated version of an RST document + +set -e +set -x + +DOCNAME=doc +DIRECTORY=doc + +# This function sets the following global variables +# - LANG_INDEX : filename which contains the language index +# - HAS_LANG : 1 (there are languages other than English), 0 (English only) +function prepare_language_index { + # Global variables + HAS_LANG=0 + LANG_INDEX=`mktemp` + trap "rm -f -- $LANG_INDEX" EXIT + + cat <> $LANG_INDEX +[ +\`English <__BASE__/__INDEX__>\`__ +EOF + + # Generate language index file + for locale in `find ${DIRECTORY}/source/locale/ -maxdepth 1 -type d` ; do + # skip if it is not a valid language translation resource. + if [ ! -e ${locale}/LC_MESSAGES/${DOCNAME}.po ]; then + continue + fi + language=$(basename $locale) + + # Reference translated document from index file + echo -n "| " >> $LANG_INDEX + HAS_LANG=1 + get_lang_name_prog=$(dirname $0)/docstheme-lang-display-name.py + name=`python3 $get_lang_name_prog $language` + echo "\`$name <__BASE__/${language}/__INDEX__>\`__" >> $LANG_INDEX + done + + cat <> $LANG_INDEX +] + +EOF +} + +function _add_language_index { + local target_file=$1 + local basepath=$2 + + local basename + basename=$(echo $target_file | sed -e "s|$DIRECTORY/source/||" -e "s|\.rst$||") + path_to_top_level=$(dirname $basename | sed -e 's|[^./]\+|..|g') + + local _basepath + if [ "$basepath" = "." -a "$path_to_top_level" = "." ]; then + _basepath="." + elif [ "$basepath" = "." ]; then + _basepath=$path_to_top_level + elif [ "$path_to_top_level" = "." ]; then + _basepath=$basepath + else + _basepath="$basepath/$path_to_top_level" + fi + + cp -p $target_file $target_file.backup + sed -e "s|__BASE__|$_basepath|" -e "s|__INDEX__|$basename.html|" $LANG_INDEX > $target_file + cat $target_file.backup >> $target_file +} + +function add_language_index_to_localized { + for f in `find $DIRECTORY/source -name '*.rst'`; do + _add_language_index $f .. + done +} + +function add_language_index_to_original { + for f in `find $DIRECTORY/source -name '*.rst'`; do + cp -p $f.backup $f + _add_language_index $REFERENCES $f . + done +} + +function recover_rst_files { + for f in `find $DIRECTORY/source -name '*.rst'`; do + mv $f.backup $f + done +} + +sphinx-build -a -W -b gettext \ + -d ${DIRECTORY}/build/doctrees.gettext \ + ${DIRECTORY}/source ${DIRECTORY}/source/locale/ + +prepare_language_index +if [ "$HAS_LANG" = "0" ]; then + exit 0 +fi +# Now add our references to the beginning of the index file. We cannot do this +# earlier since the sphinx commands will read this file. +# Ensure to revert any changes to the index file. +add_language_index_to_localized + +# check all language translation resource +for locale in `find ${DIRECTORY}/source/locale/ -maxdepth 1 -type d` ; do + # skip if it is not a valid language translation resource. + if [ ! -e ${locale}/LC_MESSAGES/${DOCNAME}.po ]; then + continue + fi + language=$(basename $locale) + + echo "===== Building $language translation =====" + + # prepare all translation resources + for pot in ${DIRECTORY}/source/locale/*.pot ; do + # get filename + potname=$(basename $pot) + resname=${potname%.pot} + # merge all translation resources + msgmerge --silent -o \ + ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${resname}.po \ + ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${DOCNAME}.po \ + ${DIRECTORY}/source/locale/${potname} + # compile all translation resources + msgfmt -o \ + ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${resname}.mo \ + ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${resname}.po + done + + # build translated guide + # TODO(amotoki): Enable -W option in translated version + sphinx-build -a -b html -D language=${language} \ + -d ${DIRECTORY}/build/doctrees.languages/${language} \ + ${DIRECTORY}/source ${DIRECTORY}/build/html/${language} + + # remove newly created files + git clean -f -q ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/*.po + git clean -f -x -q ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/*.mo + git clean -f -x -q ${DIRECTORY}/source/locale/.doctrees + # revert changes to po file + git reset -q ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${DOCNAME}.po + git checkout -q -- ${DIRECTORY}/source/locale/${language}/LC_MESSAGES/${DOCNAME}.po +done + +# remove newly created pot files +rm -f ${DIRECTORY}/source/locale/*.pot + +add_language_index_to_original + +# build English document +sphinx-build -a -W -b html \ + -d ${DIRECTORY}/build/doctrees \ + ${DIRECTORY}/source ${DIRECTORY}/build/html/ + +recover_rst_files diff --git a/bin/docstheme-lang-display-name.py b/bin/docstheme-lang-display-name.py new file mode 100755 index 0000000..79301f6 --- /dev/null +++ b/bin/docstheme-lang-display-name.py @@ -0,0 +1,28 @@ +#!/usr/bin/env python +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import sys + +import babel + +# Print full name of short language code, e.g. +# returns "Deutsch" for "de". + +lang_code = sys.argv[1] +try: + l = babel.Locale.parse(lang_code) + print(l.get_display_name()) +except Exception: + print(lang_code) diff --git a/releasenotes/notes/add-translations-9238b0f56b677a6b.yaml b/releasenotes/notes/add-translations-9238b0f56b677a6b.yaml new file mode 100644 index 0000000..0bae3df --- /dev/null +++ b/releasenotes/notes/add-translations-9238b0f56b677a6b.yaml @@ -0,0 +1,8 @@ +--- +features: + - | + Add tools for building translated documents. The file + ``docstheme-build-translated.sh`` will look for translations and + build translated documents for all languages that exist. + Invoke ``docstheme-build-translated.sh`` from tox.ini instead of running + ``sphinx-build`` directly. diff --git a/setup.cfg b/setup.cfg index f04c4c9..cf1aca9 100644 --- a/setup.cfg +++ b/setup.cfg @@ -26,6 +26,9 @@ setup-hooks = [files] packages = openstackdocstheme +scripts = + bin/docstheme-build-translated.sh + bin/docstheme-lang-display-name.py [build_sphinx] all_files = 1