How to improve re-make speed on Blender documentation translation

[Hoang Tran]

I am translating the Blender reference manual pages (https://docs.blender.org/manual/vi/3.0/index.html) to Vietnamese and in the past all PO files, with corresponding directories are generated on 

'make gettext' 

then the process of making a language will based on changes in that 

build/gettext 

directory to regenerate HTML files in the 

build/html

directory.

This process has the advantages that only changed files are grouped in the set of changed files and hence the process 'remake' after changes reduces the amount of files that needed to be reconstructed.

However, with the amount of duplication texts occurring in this method over pages, Blender has decided to generate a SINGLE po file, called 

'blender_manual.po'

in a directory reserved for the set of language, for example, for Vietnamese, it would be in:

locale/vi/LC_MESSAGES

directory.

This is good for removing duplication redundancies. HOWEVER, the downside is that during the process of translating the document, translators, like me, often need to remake the changes, often just after a page or even just a few lines, to visualise what changes looked like in HTML format, so I can adjust the translation, the code included etc...

If you can download the blender_docs, as instructed in this page (https://docs.blender.org/manual/en/3.0/about/contribute/install/index.html) for example, direct download the documentation repository would be:

svn checkout https://svn.blender.org/svnroot/bf-manual/trunk/blender_docs

then

cd blender_docs

make

would produce an English default set of files

Now if you do the following command from the 'blender_docs' directory:

svn checkout https://svn.blender.org/svnroot/bf-manual-translations/trunk/blender_docs/locale/vi locale/vi

then do:

export BF_LANG=vi; make gettext; make html

and follow the instruction on the command line to open the page. Then making some small changes by 

cd locale/vi/LC_MESSAGES

touch blender_manual.po

then run make command again:

export BF_LANG=vi; make html

you will see the report:

Running Sphinx v4.1.1

For security reason, parallel mode is disabled on macOS and python3.8 and above. For more details, please read https://github.com/sphinx-doc/sphinx/issues/6803

loading translations [vi]... done

loading pickled environment... done

building [mo]: targets for 1 po files that are out of date

writing output... [100%] ../locale/vi/LC_MESSAGES/blender_manual.mo                                                     

building [html]: targets for 0 source files that are out of date

updating environment: 0 added, 1803 changed, 0 removed

indicating 1803 files has been changed.

This information is TRUE, and FALSE at the same time.

It is TRUE that the file has been changed and that POTENTIALLY affect ALL html files, but it is FALSE because NONE of the HTML files has been changed, just the TIMESTAMP that was changed.

The structure of the 

'blender_manual.po'

is like this:

#: ../../manual/about/contribute/index.rst:18 ../../manual/about/index.rst:20

#: ../../manual/advanced/scripting/introduction.rst:41

#: ../../manual/compositing/introduction.rst:32

#: ../../manual/getting_started/configuration/hardware.rst:163

#: ../../manual/getting_started/index.rst:5 ../../manual/index.rst:20

#: ../../manual/modeling/meshes/uv/unwrapping/introduction.rst:42

#: ../../manual/sculpt_paint/texture_paint/introduction.rst:46

msgid "Getting Started"

msgstr "Khởi Đầu -- Getting Started"

so the block of comments in the Message class, above the msgid and msgstr here, shown the actual files that uses this instance of msgid.

I was wondering if there is a way to make of the list of files in the 'comment' block to work out actual changes, and thus asking sphinx-intl to ONLY regenerate for those files ONLY.

Do you know how to overcome this remake problem?

Best regards,

Hoang Tran

[Hoang Tran]

Just a small suggestion, as I continue thinking on this problem,

if all files that has been through a

make

process can be 'remembered' of their 'hashed content value' (hash number) and be detected the second time, when

make

is carried out again, and as 'hashed numbers' are recorded and compared with the previously generated hashed values, to find out TRULY if the file's content has ACTUALLY changed or not, to generate a list of files to be remade (changed)

Just a thought. What do you think?