From 1261fd292ed712bfbebb08aedf3b89ac76a197c3 Mon Sep 17 00:00:00 2001 From: iTinkerBell Date: Mon, 1 Dec 2025 15:00:31 -0500 Subject: [PATCH] initial draft --- .../translated_doc_integration_plan.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 Boost Doc Translation/translated_doc_integration_plan.md diff --git a/Boost Doc Translation/translated_doc_integration_plan.md b/Boost Doc Translation/translated_doc_integration_plan.md new file mode 100644 index 0000000..3676415 --- /dev/null +++ b/Boost Doc Translation/translated_doc_integration_plan.md @@ -0,0 +1,55 @@ +# Integration Plan for Translated Documentation + +## Current State + +Every library contains documentation in the `doc` folder. The Weblate project creates translated documentation files in the same folder as the original files, with a language suffix (e.g., `_zh`, `_ja`). + +## Integration Logic + +### Approach 1: + +- CI/CD Build Logic + + In `ci_boost_release.py`, after all documentation is converted to HTML and before generating the original index pages, code should be added to detect translated languages and reorganize files with language suffixes (e.g., `_zh`) by moving them to `doc/{language_code}/` and removing the suffix, and update hyperlinks in all HTML files to remove suffixes. Index pages should then be generated for all supported languages including the original and translated versions. Finally, all documentation including translated versions should be archived and saved to S3 as a single archive file. + +- Website Display Logic + + When displaying documentation on the website, the user's preferred language should be detected using query parameters, cookies/session, Accept-Language header, optional IP geolocation, and website default settings. Based on the detected language, the URL for getting content from S3 should be changed to include the language code, such as `doc/{language_code}/html/`. + +- Advantages + + - Clean separation of languages in folder structure + - Simple URL structure for website routing + - Less website code changes required + - Clear organization makes it easy to add or remove languages + +- Disadvantages + + - Requires processing all HTML files to update hyperlinks + - More complex reorganization logic needed + - Files are moved from original locations, which may affect existing references + - Need to handle both root `doc/` and library-specific `libs/{library}/doc/` folders during reorganization + +### Approach 2: + +- CI/CD Build Logic + + In `ci_boost_release.py`, generate index pages for different languages and save them in the same folder structure as the original index files. + +- Website Display Logic + + The documentation is displayed using URLs that include a language suffix in the filename, e.g. `/doc/libs/latest/libs/unordered/doc/html/unordered/intro_zh.html`. The language-specific content should be served by detecting the user's preferred language and serving the corresponding file with the appropriate suffix. + +- Advantages + + - Minimal changes to existing file structure + - No need to reorganize or move files + - Original file locations remain unchanged + - Less risk of breaking existing links or references + +- Disadvantages + + - Requires complex logic for generating index files for each language + - More complex URL routing logic needed on website to handle suffix-based file serving + - Less clear organization for managing multiple languages + - Index files need to reference translated files with suffixes, complicating link generation