Cara Menginternasionalkan Sphinx (i18n)

Dari default setelah eksekusi sphinx-quickstart, bagaimana cara mendapatkan direktori khusus bahasa seperti yang digunakan oleh Read The Docs?

Saya memulai situs dokumentasi Sphinx baru yang dihosting oleh GitHub Pages, dibuat dengan GitHub Actions, dan menggunakan tema Read The Docs. Pada dasarnya saya mencoba membuat ulang Read The Docs tetapi tanpa iklan atau pencarian di sisi server.

Saya tidak akan bisa menerjemahkan apa pun untuk waktu yang lama, namun saya ingin memastikan bahwa proyek baru saya siap untuk diterjemahkan di lain waktu. Yang paling spesifik, saya ingin memastikan bahwa tautan permanen ke dokumentasi saya tidak akan berubah setelah saya menambahkan terjemahan. Untuk itu, saya ingin membuat URL dokumentasi saya menyertakan bahasa di URL (/en/stable/), misalnya:

Saya mengikuti Panduan Sphinx untuk Internasionalisasi dan mengatur Variabel language dan locale_dirs di conf.py:

language = 'en'
locale_dirs = ['locale/']
gettext_compact = True

Sayangnya, setelah perubahan di atas, make html dan make -e SPHINXOPTS="-D language='en'" html masih menghasilkan file tanpa subdirektori en

user@host:~/docs$ tree -L 2 _build
_build
├── doctrees
│   ├── environment.pickle
│   └── index.doctree
└── html
    ├── genindex.html
    ├── index.html
    ├── objects.inv
    ├── search.html
    ├── searchindex.js
    ├── _sources
    └── _static

Apakah saya melewatkan sesuatu atau dokumentasinya melewatkan sesuatu? Bagaimana cara menyiapkan instalasi Sphinx baru dengan default untuk membangun html khusus bahasa dengan make?


internationalization locale python-sphinx read-the-docs
person Michael Altfield    schedule 13.07.2020    source sumber

Jawaban (1)


arrow_upward
3
arrow_downward

Kebenaran yang tidak terdokumentasikan adalah sphinx tidak melakukan hal ini. Faktanya, fungsionalitas sphinx i18n menghentikan alur kerja untuk membangun semua direktori khusus bahasa Anda. Secara implisit Anda harus mendesain & membungkus sphinx-build dengan skrip Anda sendiri untuk menyiapkannya.

Untuk menerjemahkan file sphinx reST Anda ke bahasa lain, Anda tidak perlu memperbarui sendiri file '.rst' Anda. Sphinx sudah memahami seperti apa sebuah blok teks, dan ia dapat membagi string judul, keterangan, paragraf yang dipisahkan dua baris baru, dll ke dalam string sumber unik (msgstr), dan memasukkannya ke dalam file bahasa sumber '.pot' dan file bahasa tujuan '.po'.

Pertama, jalankan make gettext dari direktori 'docs/'. Ini memberitahu sphinx untuk mengurai file reST Anda dan secara otomatis menemukan sekumpulan string yang akan diterjemahkan dan memberi mereka msgid unik.

user@host:~/rtd-github-pages$ cd docs/
user@host:~/rtd-github-pages/docs$ ls
autodoc.rst  buildDocs.sh  conf.py.orig  locales   Makefile
_build       conf.py       index.rst     make.bat  _static
user@host:~/rtd-github-pages/docs$ 
 
user@host:~/rtd-github-pages/docs$ make gettext
Running Sphinx v1.8.4
making output directory...
building [gettext]: targets for 0 template files
building [gettext]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
Hello Worldrces... [ 50%] autodoc                                               
reading sources... [100%] index                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
writing message catalogs... [100%] index                                        
build succeeded.
 
The message catalogs are in _build/gettext.
user@host:~/rtd-github-pages/docs$

Eksekusi di atas akan menghasilkan file-file berikut

user@host:~/rtd-github-pages/docs$ ls _build/gettext/
autodoc.pot  index.pot
user@host:~/rtd-github-pages/docs$

Berikut cuplikan dari '_build/gettext/index.pot' yang menunjukkan dua string di halaman utama dokumentasi kami yang akan kami terjemahkan dari bahasa Inggris ke bahasa Spanyol.

user@host:~/rtd-github-pages/docs$ grep -m2 -A2 .rst _build/gettext/index.pot 
#: ../../index.rst:7
msgid "Welcome to helloWorld's documentation!"
msgstr ""
--
#: ../../index.rst:9
msgid "Contents:"
msgstr ""
user@host:~/rtd-github-pages/docs$

Berikutnya, izinkan sphinx menyiapkan beberapa file '.po' berbahasa tujuan Spanyol dari file '.pot' bahasa sumber yang kami buat di atas.

Sebelum melanjutkan ke langkah ini, Anda perlu menginstal sphinx-intl dan modul python Stemmer. Jika Anda menggunakan distro berbasis Debian, Anda dapat melakukannya dengan perintah berikut.

sudo apt-get install -y sphinx-intl python3-stemmer

Jalankan perintah berikut untuk menyiapkan file terjemahan khusus bahasa Spanyol kami.

user@host:~/rtd-github-pages/docs$ sphinx-intl update -p _build/gettext -l es
Create: locales/es/LC_MESSAGES/index.po
Create: locales/es/LC_MESSAGES/autodoc.po
user@host:~/rtd-github-pages/docs$

Eksekusi di atas menghasilkan dua file '.po': satu untuk masing-masing file bahasa sumber '.pot', yang berkorelasi langsung dengan masing-masing dua file '.rst' (index.rst dan autodoc.rst). Sempurna.

Jika kita mengambil file baru 'docs/locales/es/LC_MESSAGES/index.po' khusus bahasa Spanyol, kita akan melihat bahwa file tersebut memiliki konten yang sama dengan file '.pot' sumber.

user@host:~/rtd-github-pages/docs$ grep -m2 -A2 .rst locales/es/LC_MESSAGES/index.po 
#: ../../index.rst:7
msgid "Welcome to helloWorld's documentation!"
msgstr ""
--
#: ../../index.rst:9
msgid "Contents:"
msgstr ""
user@host:~/rtd-github-pages/docs$

File '.po' khusus bahasa ini adalah tempat kami melakukan penerjemahan. Jika proyek Anda besar, Anda mungkin ingin menggunakan program khusus atau layanan untuk menerjemahkan file-file ini. Namun untuk lebih jelasnya kita langsung saja mengedit filenya.

user@host:~/rtd-github-pages/docs$ perl -pi -0e "s^(msgid \"Welcome to helloWorld's documentation\!\"\n)msgstr \"\"^\1msgstr \"¡Bienvenido a la documentación de helloWorld\!\"^" locales/es/LC_MESSAGES/index.po
user@host:~/rtd-github-pages/docs$ perl -pi -0e "s^(msgid \"Contents:\"\n)msgstr \"\"^\1msgstr \"Contenidos:\"^" locales/es/LC_MESSAGES/index.po
user@host:~/rtd-github-pages/docs$ 
 
user@host:~/rtd-github-pages/docs$ grep -m2 -A2 .rst locales/es/LC_MESSAGES/index.po 
#: ../../index.rst:7
msgid "Welcome to helloWorld's documentation!"
msgstr "¡Bienvenido a la documentación de helloWorld!"
--
#: ../../index.rst:9
msgid "Contents:"
msgstr "Contenidos"
user@host:~/rtd-github-pages/docs$

Seperti yang Anda lihat, eksekusi di atas mengisi konten msgstr "" dengan terjemahan bahasa Spanyol dari baris msgid yang sesuai di atasnya dalam bahasa asli (Inggris).

Sekarang mari kita buat dua versi konten statis html kita: [1] dalam bahasa Inggris dan [2] dalam bahasa Spanyol.

user@host:~/rtd-github-pages/docs$ sphinx-build -b html . _build/html/en -D language='en'
Running Sphinx v1.8.4
loading translations [en]... done
making output directory...
building [mo]: targets for 0 po files that are out of date
building : targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
Hello Worldrces... [ 50%] autodoc                                               
reading sources... [100%] index                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
generating indices... genindex py-modindex
highlighting module code... [100%] helloWorld                                   
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
 
The HTML pages are in _build/html/en.
user@host:~/rtd-github-pages/docs$
 
user@host:~/rtd-github-pages/docs$ sphinx-build -b html . _build/html/es -D language='es'
Running Sphinx v1.8.4
loading translations [es]... done
making output directory...
building [mo]: targets for 1 po files that are out of date
writing output... [100%] locales/es/LC_MESSAGES/index.mo                        
building : targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
Hello Worldrces... [ 50%] autodoc                                               
reading sources... [100%] index                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                  
generating indices... genindex py-modindex
highlighting module code... [100%] helloWorld                                   
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in Spanish (code: es) ... done
dumping object inventory... done
build succeeded.
 
The HTML pages are in _build/html/es.
user@host:~/rtd-github-pages/docs$
 
user@host:~/rtd-github-pages/docs$ firefox _build/html/en/index.html _build/html/es/index.html &
[1] 12134
user@host:~/rtd-github-pages/docs$

Perintah firefox dalam eksekusi di atas akan membuka browser Anda dengan dua tab: (1) dalam bahasa Inggris dan (2) dalam bahasa Spanyol.

Untuk informasi selengkapnya, lihat artikel ini tentang cara menyiapkan internasionalisasi di Sphinx.

person Michael Altfield    schedule 23.07.2020
comment
Anda mungkin juga ingin mempertimbangkan penggunaan rinoh untuk menghasilkan PDF dengan sphinx github.com/maltfield/rtd-github-pages/blob/ - person Michael Altfield; 20.08.2020