วิธีการทำให้สฟิงซ์เป็นสากล (i18n)

จากค่าเริ่มต้นหลังจากการดำเนินการ sphinx-quickstart ฉันจะรับไดเร็กทอรีเฉพาะภาษาเหมือนกับที่ Read The Docs ใช้ได้อย่างไร

ฉันกำลังเริ่มไซต์เอกสารสฟิงซ์ใหม่ซึ่งโฮสต์โดย GitHub Pages ซึ่งสร้างขึ้นด้วย GitHub Actions และใช้ธีม Read The Docs โดยพื้นฐานแล้วฉันกำลังพยายามสร้าง Read The Docs ขึ้นมาใหม่ แต่ไม่มีโฆษณาหรือการค้นหาฝั่งเซิร์ฟเวอร์

ฉันไม่สามารถแปลอะไรได้จริงๆ เป็นเวลานาน แต่ฉันต้องการให้แน่ใจว่าโปรเจ็กต์ใหม่ของฉันพร้อมที่จะแปลในภายหลัง โดยเฉพาะอย่างยิ่ง ฉันต้องการให้แน่ใจว่าลิงก์ถาวรไปยังเอกสารของฉันจะไม่เปลี่ยนแปลงหลังจากที่ฉันเพิ่มคำแปล ด้วยเหตุนี้ ฉันต้องการให้ URL เอกสารของฉันรวมภาษาใน URL (/en/stable/) เช่น:

ฉันปฏิบัติตาม Sphinx Guide to Internationalization และตั้งค่า ตัวแปร language และ locale_dirs ใน conf.py:

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

น่าเสียดายที่หลังจากการเปลี่ยนแปลงข้างต้น make html และ make -e SPHINXOPTS="-D language='en'" html ยังคงสร้างไฟล์โดยไม่มีไดเร็กทอรีย่อย 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

ฉันขาดอะไรบางอย่างหรือเอกสารขาดหายไปบางอย่าง? ฉันจะตั้งค่าการติดตั้งสฟิงซ์ใหม่ด้วยค่าเริ่มต้นเพื่อสร้างเป็น html เฉพาะภาษาด้วย make ได้อย่างไร


internationalization locale python-sphinx read-the-docs
person Michael Altfield    schedule 13.07.2020    source แหล่งที่มา

คำตอบ (1)


arrow_upward
3
arrow_downward

ความจริงที่ไม่มีเอกสารก็คือสฟิงซ์ไม่ได้ทำเช่นนี้ ในความเป็นจริง ฟังก์ชันการทำงานของ sphinx i18n หยุดทำงานเพียงขั้นตอนเดียวสำหรับการสร้างไดเร็กทอรีเฉพาะภาษาของคุณทั้งหมด โดยนัยคือคุณต้องออกแบบและล้อม sphinx-build ด้วยสคริปต์ของคุณเองเพื่อตั้งค่านี้

หากต้องการแปลไฟล์ Sphinx reST เป็นภาษาอื่น คุณไม่จำเป็นต้องอัปเดตไฟล์ '.rst' ด้วยตนเอง สฟิงซ์เข้าใจแล้วว่าบล็อกข้อความมีลักษณะอย่างไร และสามารถแบ่งสตริงหัวเรื่อง คำอธิบาย ย่อหน้าที่คั่นด้วยบรรทัดใหม่ ฯลฯ ออกเป็นสตริงต้นฉบับที่ไม่ซ้ำกัน (msgid) และใส่ลงในไฟล์ภาษาต้นฉบับ '.pot' และไฟล์ภาษาปลายทาง '.po'

ขั้นแรก ให้รัน make gettext จากไดเร็กทอรี 'docs/' สิ่งนี้จะบอกสฟิงซ์ให้แยกวิเคราะห์ไฟล์ reST ของคุณและค้นหาสตริงที่จะแปลโดยอัตโนมัติและให้ msgid ที่ไม่ซ้ำกับพวกมัน

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$

การดำเนินการข้างต้นควรสร้างไฟล์ต่อไปนี้

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

นี่เป็นตัวอย่างจาก '_build/gettext/index.pot' ที่แสดงสองสตริงในหน้าหลักของเอกสารประกอบของเราซึ่งเราจะแปลจากภาษาอังกฤษเป็นภาษาสเปน

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$

ต่อไป เรามาบอกสฟิงซ์ให้เตรียมไฟล์ '.po' ภาษาปลายทางภาษาสเปนจากไฟล์ '.pot' ที่เป็นภาษาปลายทางที่เราสร้างขึ้นข้างต้น

ก่อนที่จะดำเนินการขั้นตอนนี้ คุณจะต้องติดตั้ง sphinx-intl และโมดูล python Stemmer หากคุณใช้ดิสโทรแบบ Debian คุณสามารถทำได้ด้วยคำสั่งต่อไปนี้

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

ดำเนินการคำสั่งต่อไปนี้เพื่อเตรียมไฟล์แปลเฉพาะภาษาสเปนของเรา

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$

การดำเนินการข้างต้นได้สร้างไฟล์ '.po' สองไฟล์: หนึ่งไฟล์สำหรับไฟล์ภาษาต้นฉบับ '.pot' แต่ละไฟล์ ซึ่งสัมพันธ์โดยตรงกับไฟล์ '.rst' แต่ละไฟล์ของเรา (index.rst และ autodoc.rst) สมบูรณ์แบบ.

หากเรา grep ไฟล์ 'docs/locales/es/LC_MESSAGES/index.po' เฉพาะภาษาสเปนใหม่ เราจะพบว่ามีเนื้อหาเหมือนกับไฟล์ต้นฉบับ '.pot'

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$

ไฟล์ '.po' เฉพาะภาษาเหล่านี้เป็นที่ที่เราแปลจริงๆ หากคุณเป็นโครงการขนาดใหญ่ คุณอาจต้องการใช้โปรแกรมพิเศษหรือบริการ เพื่อแปล ไฟล์เหล่านี้ แต่เพื่อความชัดเจน เราจะแก้ไขไฟล์โดยตรง

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$

อย่างที่คุณเห็น การดำเนินการข้างต้นเต็มไปด้วยเนื้อหา msgstr "" พร้อมด้วยคำแปลภาษาสเปนของบรรทัด msgid ที่เกี่ยวข้องด้านบนในภาษาต้นฉบับ (ภาษาอังกฤษ)

ตอนนี้เรามาสร้างเนื้อหาคงที่ html ของเราสองเวอร์ชัน: [1] เป็นภาษาอังกฤษและ [2] เป็นภาษาสเปน

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$

คำสั่ง firefox ในการดำเนินการข้างต้นควรเปิดเบราว์เซอร์ของคุณด้วยสองแท็บ: (1) ในภาษาอังกฤษและ (2) ในภาษาสเปน

สำหรับข้อมูลเพิ่มเติม โปรดดูบทความนี้ใน วิธีการตั้งค่า ความเป็นสากลในสฟิงซ์

person Michael Altfield    schedule 23.07.2020
comment
คุณอาจต้องการพิจารณาใช้ rinoh เพื่อสร้าง PDF ด้วยสฟิงซ์ github.com/maltfield/rtd-github-pages/blob/ - person Michael Altfield; 20.08.2020