translable files

[speco29]

Build the sphinx setup and pot files. @OriolAbril

[speco29]

Regarding Makefile, make.bat index.rst and conf.py. These would be great if we were starting an sphinx project from scratch, but we already have one that we build through jupyterbook and we want to build through sphinx directly instead. This means we need to translate the yaml config to conf.py and as little else as possible. We already have build instructions in the readme and infrastructure to build the website that don't use any makefile, so we would need to update those to modify as little as possible the workflow contributors are already used to.

When I fetched the files in .pot format, I thought every file which was in .md format will be fetched, I don't understand why only index file was fetched.

[OriolAbril]

When I fetched the files in .pot format, I thought every file which was in .md format will be fetched, I don't understand why only index file was fetched.

This is due to the conf.py not being equivalent to the current config.yml. The conf.py file is what indicates how the website should be built. By default sphinx only considers .rst files as sources but there are extensions that allow using markdown files as sources too. If in addition to generating the translatable files you also attempted to build the html website you should also see that the look is very different (conf.py also defines the theme to be used) and the sidebar should would also be different (in addition to look different due to the theme have different elements or no elements in it). The sidebar is populated from the toctree directives within the files as default. Given the toctree directive in index.rst is empty I suspect it would be empty too. Again, similarly to parsing markdown files, there are also extensions available to instead populate the sidebar from the _toc.yml file.

[speco29]

When I fetched the files in .pot format, I thought every file which was in .md format will be fetched, I don't understand why only index file was fetched.

This is due to the conf.py not being equivalent to the current config.yml. The conf.py file is what indicates how the website should be built. By default sphinx only considers .rst files as sources but there are extensions that allow using markdown files as sources too. If in addition to generating the translatable files you also attempted to build the html website you should also see that the look is very different (conf.py also defines the theme to be used) and the sidebar should would also be different (in addition to look different due to the theme have different elements or no elements in it). The sidebar is populated from the toctree directives within the files as default. Given the toctree directive in index.rst is empty I suspect it would be empty too. Again, similarly to parsing markdown files, there are also extensions available to instead populate the sidebar from the _toc.yml file.

Okay, I understand now, I'll have to edit the conf.py file manually according to the needs and also will need to download extensions for markdown files.

[speco29]

The extensions should be like this - https://github.com/numfocus/disc-unconference-2023-projects/blob/main/unconference/conf.py, right?

[OriolAbril]

It will look very similar yes, but there will also be some differences. I'd recommend starting with the conf.py version automatically generated by jupyterbook: https://jupyterbook.org/en/stable/reference/cli.html#jupyter-book-config. Try building the website in html mode and see if you get the same result as the published one

[speco29]

. I'd recommend starting with the conf.py version automatically generated by jupyterbook: https://jupyterbook.org/en/stable/reference/cli.html#jupyter-book-config.

I ran those commands and it has built a conf.py file in DISCOVER folder.

Also I ran this command line sphinx-build -b gettext -c source DISCOVER _locale and it has generated a _locale folder in the repo that contains the following files:

[OriolAbril]

sphinx-build -b gettext -c source DISCOVER _locale

The -c source part is saying to use the conf.py in the source folder, not the one you have just generated in the DISCOVER folder, it should be omitted.

I would also advise against using _locale as the folder name for the output. There is nothing technically wrong with it, but one of the most common conventions with translations is to place the translated files/messages in the locale/locales folder. The output of gettext are .pot files which will never store any translations in them, so you'll probably have to distinguish between _locale (not version controled, has .pot files) and locale (version controled, has .po files with the actual translations) folder in the future which is bound to be confusing.

[speco29]

I have made the folders and generated the files, @OriolAbril please have a look and let me know about the changes I have made. I think this time, I have done something right 😏

[OriolAbril]

Yes! Now it has the .po files with all the translatable messages in the project. What is left is mosly cleanup. The PR should update 3 things only:

• conf.py
• Readme.md (or an alternative markdown file with instructions on how to generate .pot files, then update the .po files)
• Add the locale/locales folder.

[speco29]

• conf.py

The new conf.py is generated by jupyterbook-command line, is there something that I should update in it manually? I removed the source folder, now there is only one folder that is DISCOVER and in that folder the conf.py exist.

[speco29]

• Readme.md (or an alternative markdown file with instructions on how to generate .pot files, then update the .po files)

I will look through how https://github.com/numfocus/disc-unconference-2023-projects/blob/main/README.md have added instructions to generate these files and will update our READ.md accordingly.

[speco29]

• Add the locale/locales folder.

I have added locale_source folder that contains the .pot files and locales folder that contains the .po files. Is there something else to be added?

[speco29]

I think updating the READ.md file will increase the length of file more than needed and it will not be appropriate to have instructions there, so I have made a separate markdown file i.e. Translation.md that has every instruction.

I might have missed something, so let me know if there is something else need to be added.

[speco29]

• _config.toml -> it will no longer be used, and we want a single source of truth for the website configuration and build process

I couldn't find any _config.toml, do you mean _config.yml or maybe _toc.yml perhaps?

[OriolAbril]

I couldn't find any _config.toml, do you mean _config.yml or maybe _toc.yml perhaps?

I meant _config.yml, yes. _toc.yml needs to be kept as it is critical to building the website correctly (with either conf.py or _config.yml).

Also, as we agreed to start with Spanish as first translation target we should delete the en folder in locales and instead generate the es one.

I will try to review the changes themselves later today but I might get to it tomorrow eventually.

[speco29]

@speco29 is there anything else you want to add to the PR before it is merged?

I think it can be merged like that and then we iterate on follow-up PRs, that would allow #329 to build on top of this which already has conf.py

This PR was meant for sphinx setup and updation of exisiting files, which I think is done. So I think this PR is ready to be merged, also #329 has many commits that has already been covered in this PR, we can merge this PR and then #329 can be updated and done accordingly.