├── .github ├── FUNDING.yml ├── dependabot.yml └── workflows │ ├── ci.yml │ ├── deploy-docs.yml │ └── deploy-release.yml ├── .gitignore ├── LICENSE ├── Makefile ├── README.md ├── config_update_to_v1.py ├── docs ├── assets │ ├── image_non_localized.png │ ├── logo_by_maxicons.png │ └── spaceship_help_translating_item.png ├── changelog.md ├── getting-started │ ├── installation.md │ ├── philosophy.md │ └── quick-start.md ├── index.fr.md ├── index.md ├── overrides │ ├── home.fr.html │ ├── home.html │ └── partials │ │ └── copyright.html └── setup │ ├── choosing-the-structure.md │ ├── controlling-your-builds.md │ ├── index.md │ ├── localizing-navigation.md │ ├── plugins-compatibility.md │ ├── setting-up-languages.md │ ├── setting-up-material.md │ ├── setting-up-search.md │ ├── translating-content.md │ ├── upgrading-to-1.md │ ├── using-alternates.md │ └── using-i18n-context.md ├── mkdocs.yml ├── mkdocs_static_i18n ├── __init__.py ├── config.py ├── custom_i18n_sitemap │ └── sitemap.xml ├── folder.py ├── plugin.py ├── reconfigure.py ├── suffix.py └── utils.py ├── pyproject.toml ├── setup.py └── tests ├── admonitions ├── index.fr.md └── index.md ├── conftest.py ├── details ├── index.fr.md └── index.md ├── docs_folder_structure_one_language ├── assets │ └── image_non_localized.png ├── en │ ├── english_default │ │ └── index.md │ ├── image.fake │ ├── image.png │ ├── index.md │ ├── topic1 │ │ └── named_file.md │ └── topic2 │ │ ├── 1.1.filename.html │ │ ├── README.md │ │ ├── release_notes_17.1.md │ │ └── release_notes_17.2.md └── fr │ ├── french_only │ └── index.md │ ├── image.fake │ ├── image.png │ ├── index.md │ ├── topic1 │ └── named_file.md │ └── topic2 │ ├── 1.1.filename.html │ ├── README.md │ ├── release_notes_17.1.md │ └── release_notes_17.2.md ├── docs_folder_structure_two_languages ├── assets │ └── image_non_localized.png ├── en │ ├── english_default │ │ └── index.md │ ├── image.fake │ ├── image.png │ ├── index.md │ ├── topic1 │ │ └── named_file.md │ └── topic2 │ │ ├── 1.1.filename.html │ │ ├── README.md │ │ ├── release_notes_17.1.md │ │ └── release_notes_17.2.md └── fr │ ├── french_only │ └── index.md │ ├── image.fake │ ├── image.png │ ├── index.md │ ├── topic1 │ └── named_file.md │ └── topic2 │ ├── 1.1.filename.html │ └── README.md ├── docs_folder_structure_two_languages_with_default ├── assets │ └── image_non_localized.png ├── en │ ├── english_default │ │ └── index.md │ ├── image.fake │ ├── image.png │ ├── index.md │ ├── topic1 │ │ └── named_file.md │ └── topic2 │ │ ├── 1.1.filename.html │ │ ├── README.md │ │ ├── release_notes_17.1.md │ │ └── release_notes_17.2.md └── fr │ ├── french_only │ └── index.md │ ├── image.fake │ ├── image.png │ ├── index.md │ ├── topic1 │ └── named_file.md │ └── topic2 │ ├── 1.1.filename.html │ ├── README.md │ ├── release_notes_17.1.md │ └── release_notes_17.2.md ├── docs_suffix_structure_one_language ├── assets │ └── image_non_localized.png ├── english_default │ └── index.en.md ├── french_only │ └── index.fr.md ├── image.en.fake ├── image.en.png ├── image.fr.fake ├── image.fr.png ├── index.fr.md ├── index.md ├── topic1 │ ├── named_file.en.md │ └── named_file.fr.md └── topic2 │ ├── 1.1.filename.fr.html │ ├── 1.1.filename.html │ ├── README.fr.md │ ├── README.md │ ├── release_notes_17.1.md │ └── release_notes_17.2.md ├── docs_suffix_structure_two_languages ├── assets │ └── image_non_localized.png ├── english_default │ └── index.en.md ├── french_only │ └── index.fr.md ├── image.en.fake ├── image.en.png ├── image.fr.fake ├── image.fr.png ├── index.fr.md ├── index.md ├── topic1 │ ├── named_file.en.md │ └── named_file.fr.md └── topic2 │ ├── 1.1.filename.fr.html │ ├── 1.1.filename.html │ ├── README.fr.md │ ├── README.md │ ├── release_notes_17.1.md │ └── release_notes_17.2.md ├── hooks.py ├── hooks_jinja_on_env.py ├── mkdocs.yml ├── structures └── control │ ├── en_fr │ ├── docs │ │ ├── assets │ │ │ └── image_non_localized.png │ │ ├── english_default │ │ │ └── index.md │ │ ├── fr │ │ │ ├── assets │ │ │ │ └── image_non_localized.png │ │ │ ├── english_default │ │ │ │ └── index.md │ │ │ ├── french_only │ │ │ │ └── index.md │ │ │ ├── image.fake │ │ │ ├── image.png │ │ │ ├── index.md │ │ │ ├── topic1 │ │ │ │ └── named_file.md │ │ │ └── topic2 │ │ │ │ ├── 1.1.filename.html │ │ │ │ ├── README.md │ │ │ │ ├── release_notes_17.1.md │ │ │ │ └── release_notes_17.2.md │ │ ├── image.fake │ │ ├── image.png │ │ ├── index.md │ │ ├── topic1 │ │ │ └── named_file.md │ │ └── topic2 │ │ │ ├── 1.1.filename.html │ │ │ ├── README.md │ │ │ ├── release_notes_17.1.md │ │ │ └── release_notes_17.2.md │ └── mkdocs.yml │ ├── en_only │ ├── docs │ │ ├── assets │ │ │ └── image_non_localized.png │ │ ├── english_default │ │ │ └── index.md │ │ ├── image.fake │ │ ├── image.png │ │ ├── index.md │ │ ├── topic1 │ │ │ └── named_file.md │ │ └── topic2 │ │ │ ├── 1.1.filename.html │ │ │ ├── README.md │ │ │ ├── release_notes_17.1.md │ │ │ └── release_notes_17.2.md │ └── mkdocs.yml │ ├── fr_only │ ├── docs │ │ ├── assets │ │ │ └── image_non_localized.png │ │ ├── french_only │ │ │ └── index.md │ │ ├── image.fake │ │ ├── image.png │ │ ├── index.md │ │ ├── topic1 │ │ │ └── named_file.md │ │ └── topic2 │ │ │ ├── 1.1.filename.html │ │ │ ├── README.md │ │ │ ├── release_notes_17.1.md │ │ │ └── release_notes_17.2.md │ └── mkdocs.yml │ ├── fr_with_default │ ├── docs │ │ ├── assets │ │ │ └── image_non_localized.png │ │ ├── english_default │ │ │ └── index.md │ │ ├── french_only │ │ │ └── index.md │ │ ├── image.fake │ │ ├── image.png │ │ ├── index.md │ │ ├── topic1 │ │ │ └── named_file.md │ │ └── topic2 │ │ │ ├── 1.1.filename.html │ │ │ ├── README.md │ │ │ ├── release_notes_17.1.md │ │ │ └── release_notes_17.2.md │ └── mkdocs.yml │ └── fr_without_default │ ├── docs │ ├── french_only │ │ └── index.md │ ├── image.fake │ ├── image.png │ ├── index.md │ ├── topic1 │ │ └── named_file.md │ └── topic2 │ │ ├── 1.1.filename.html │ │ └── README.md │ └── mkdocs.yml ├── test_admonitions.py ├── test_config.py ├── test_control.py ├── test_details.py ├── test_hooks.py ├── test_language_selector.py ├── test_languages_option.py ├── test_locale_type.py ├── test_navigation.py ├── test_rtd.py ├── test_search.py ├── test_structure_folder.py ├── test_structure_suffix.py └── theme_overrides └── content.html /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | github: ultrabug 2 | custom: https://paypal.me/alexysjacob1 3 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # To get started with Dependabot version updates, you'll need to specify which 2 | # package ecosystems to update and where the package manifests are located. 3 | # Please see the documentation for all configuration options: 4 | # https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates 5 | 6 | version: 2 7 | updates: 8 | - package-ecosystem: "pip" 9 | directory: "/" 10 | schedule: 11 | interval: "weekly" 12 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: [push, pull_request] 4 | 5 | jobs: 6 | test: 7 | strategy: 8 | max-parallel: 5 9 | matrix: 10 | python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"] 11 | os: [ubuntu-latest, windows-latest, macos-latest] 12 | # Just to slim down the test matrix: 13 | exclude: 14 | - python-version: 3.8 15 | os: macos-latest 16 | - python-version: 3.8 17 | os: windows-latest 18 | - python-version: 3.9 19 | os: ubuntu-latest 20 | - python-version: 3.10 21 | os: macos-latest 22 | - python-version: 3.10 23 | os: windows-latest 24 | runs-on: ${{ matrix.os }} 25 | steps: 26 | - uses: actions/checkout@v3 27 | - name: Setup Python ${{ matrix.python-version }} 28 | uses: actions/setup-python@v4 29 | with: 30 | python-version: ${{ matrix.python-version }} 31 | - name: Install dependencies 32 | run: | 33 | python -m pip install --upgrade hatch 34 | - name: Run tests 35 | run: | 36 | hatch run +py=${{ matrix.py || matrix.python-version }} test:test 37 | shell: bash 38 | 39 | lint: 40 | runs-on: ubuntu-latest 41 | steps: 42 | - uses: actions/checkout@v3 43 | - name: Setup Python 44 | uses: actions/setup-python@v4 45 | with: 46 | python-version: '3.13' 47 | - name: Install Python dependencies 48 | run: | 49 | python -m pip install --upgrade hatch 50 | - name: Check style 51 | if: always() 52 | run: hatch run style:check 53 | -------------------------------------------------------------------------------- /.github/workflows/deploy-docs.yml: -------------------------------------------------------------------------------- 1 | name: Deploy docs 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | 8 | jobs: 9 | build: 10 | name: Deploy docs 11 | runs-on: ubuntu-latest 12 | steps: 13 | - name: Download source 14 | uses: actions/checkout@v3 15 | - name: Install Python 16 | uses: actions/setup-python@v4 17 | with: 18 | python-version: '3.x' 19 | - name: Install Python dependencies 20 | run: | 21 | python -m pip install --upgrade hatch 22 | - name: Build site 23 | run: hatch -e doc run mkdocs build 24 | - name: Deploy to gh-pages 25 | if: github.event_name == 'push' && github.ref == 'refs/heads/main' 26 | uses: oprypin/push-to-gh-pages@v3 27 | with: 28 | publish_dir: site 29 | commit_message: 'Generate docs: ' -------------------------------------------------------------------------------- /.github/workflows/deploy-release.yml: -------------------------------------------------------------------------------- 1 | name: deploy-release 2 | 3 | on: 4 | push: 5 | tags: 6 | - '*' 7 | 8 | jobs: 9 | pypi: 10 | runs-on: ubuntu-latest 11 | steps: 12 | - uses: actions/checkout@v3 13 | - name: Setup Python 14 | uses: actions/setup-python@v4 15 | with: 16 | python-version: '3.11' 17 | - name: Install Hatch 18 | run: | 19 | python -m pip install -U hatch 20 | - name: Build package 21 | run: | 22 | hatch build 23 | - name: Publish 24 | run: | 25 | hatch publish 26 | env: 27 | HATCH_INDEX_USER: __token__ 28 | HATCH_INDEX_AUTH: ${{ secrets.PYPI_PASSWORD }} 29 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.pyc 2 | *.egg-info/ 3 | dist/ 4 | site/ 5 | .tox/ 6 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 Ultrabug 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | qa: 2 | hatch run style:format 3 | hatch run style:check 4 | 5 | clean: 6 | hatch clean 7 | 8 | release: clean qa test build 9 | hatch publish -u __token__ 10 | 11 | serve: 12 | mkdocs serve 13 | 14 | build: 15 | hatch build 16 | 17 | deploy: qa test 18 | mkdocs gh-deploy 19 | 20 | test: 21 | hatch run all 22 | 23 | changelog: 24 | cz changelog --file-name docs/changelog.md --incremental 25 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![logo by max.icons](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/docs/assets/logo_by_maxicons.png) 2 | 3 | # MkDocs static i18n plugin 4 | 5 | ![mkdocs-static-i18n pypi version](https://img.shields.io/pypi/v/mkdocs-static-i18n.svg) 6 | 7 | *The MkDocs plugin that helps you support multiple language versions of your site / documentation.* 8 | 9 | *Like what you :eyes:? Using this plugin? Give it a :star:!* 10 | 11 | The `mkdocs-static-i18n` plugin allows you to support multiple languages of your documentation by adding static translation files to your existing documentation pages. 12 | 13 | Multi language support is just **one `..md` file away**! 14 | 15 | Even better, `mkdocs-static-i18n` also allows you to build and serve localized versions of any file extension to display localized images, medias and assets. 16 | 17 | Localized images/medias/assets are just **one `..` file away**! 18 | 19 | Don't like file suffixes? You're more into a folder based structure? We got you covered as well! 20 | 21 | ## Documentation 22 | 23 | Check out the [plugins' documentation here](https://ultrabug.github.io/mkdocs-static-i18n/). 24 | 25 | TL;DR? There's a [quick start guide](https://ultrabug.github.io/mkdocs-static-i18n/getting-started/quick-start/) for you! 26 | 27 | ## Upgrading from 0.x versions 28 | 29 | :warning: Version 1.0.0 brings **breaking changes** to the configuration format of the plugin. Check out the [upgrade to v1.0.0 guide](https://ultrabug.github.io/mkdocs-static-i18n/setup/upgrading-to-1/) to ease updating your `mkdocs.yml` file! 30 | 31 | ## See it in action 32 | 33 | This plugin is proudly bringing localized content of [hundreds of projects](https://github.com/ultrabug/mkdocs-static-i18n/network/dependents) to their users. 34 | 35 | Check it out live: 36 | 37 | - [On this repository documentation](https://ultrabug.github.io/mkdocs-static-i18n/) 38 | - [On my own website: ultrabug.fr](https://ultrabug.fr) 39 | 40 | But also in our hall of fame: 41 | 42 | - [AWS Copilot CLI](https://aws.github.io/copilot-cli/) 43 | - [OWASP Top 10](https://github.com/OWASP/Top10) 44 | - [Spaceship Prompt](https://spaceship-prompt.sh/) 45 | - [FederatedAI FATE](https://fate.readthedocs.io/en/latest/) 46 | - [Privacy Guides Org](https://www.privacyguides.org/en/) 47 | - [Computer Science Self Learning Wiki](https://csdiy.wiki/) 48 | 49 | ## Contributions welcome 50 | 51 | Feel free to ask questions, enhancements and to contribute to this project! 52 | 53 | ## Development 54 | 55 | The project is managed with `hatch`. [Install `hatch`](https://hatch.pypa.io/1.9/install/#gui-installer) first. 56 | 57 | Run the tests: 58 | 59 | ```shell 60 | hatch run test:test 61 | hatch run style:check 62 | ``` 63 | 64 | Serve the documentation: 65 | 66 | ```shell 67 | hatch run doc:serve 68 | ``` 69 | 70 | ## Credits 71 | 72 | - Logo by [max.icons](https://www.flaticon.com/authors/maxicons) 73 | -------------------------------------------------------------------------------- /docs/assets/image_non_localized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/docs/assets/image_non_localized.png -------------------------------------------------------------------------------- /docs/assets/logo_by_maxicons.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/docs/assets/logo_by_maxicons.png -------------------------------------------------------------------------------- /docs/assets/spaceship_help_translating_item.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/docs/assets/spaceship_help_translating_item.png -------------------------------------------------------------------------------- /docs/changelog.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | !!!tip "Reminder" 4 | We try our best to follow [Semantic Versioning v2](https://semver.org/) starting from 1.0.0. 5 | 6 | ## 1.3.0 (2025-01-24) 7 | 8 | - **build**: test and declare support for python 3.13 (#319) 9 | - **docs**: add documentation on how to build and run the project, by Nicco Kunzmann 10 | - **docs**: add style:check to documentation, by Nicco Kunzmann 11 | - **docs**: fix-bad-example-for-lang-switcher-external-link-feature thx to @niccokunzmann 12 | - **plugin**: add admonitions translations to `pymdownx.details` (#317), by Joan Puigcerver 13 | - **plugin**: drop deprecated theme._vars and access keys directly (#315), by Joan Puigcerver 14 | - **pyproject**: fix the doc environment used to locally serve the plugin documentation 15 | 16 | ## 1.2.3 (2024-05-02) 17 | 18 | - **reconfigure**: drop incorrect log level from info to debug 19 | - **reconfigure**: file.page can be None and make plugin crash 20 | 21 | ## 1.2.2 (2024-03-01) 22 | 23 | - **build**: drop eol 3.7, add 3.12 compat and tests 24 | - **chore**: fix deprecation warning, by Kamil Krzyśków 25 | - **config**: new option "admonition_translations" to allow translating of admonitions by Michal Fapso (#293) 26 | - **folder**: correct file lookup, by Kamil Krzyśków 27 | - **plugin** fix homepage detection, by Kamil Krzyśków 28 | - **test**: add tests for folder structure, by Kamil Krzyśków 29 | 30 | ## 1.2.1 (2024-01-28) 31 | 32 | - **folder**: fix path lookup order, by Kamil Krzyśków 33 | - **on_files**: switch the file localization logic to use src_uri instead of dest_uri (#279) 34 | 35 | ## 1.2.0 (2023-10-25) 36 | 37 | - **config**: Add build_only_locale option, by Kamil Krzyśków 38 | 39 | ## 1.1.1 (2023-10-13) 40 | 41 | - **user_overrides**: extra overrides should be applied as legacy dict, thx to @Andygol 42 | - **docs**: add and correct lang config overrides examples 43 | 44 | ## 1.1.0 (2023-10-06) 45 | 46 | - **material**: add a special "null" locale to generated a fixed fixed item in the lang switcher (#270) 47 | - **reconfigure**: allow the default language to use localized files or not wrt issue #262 (#269) 48 | 49 | ## 1.0.6 (2023-09-21) 50 | 51 | - **get_file_from_path**: resolving root path '.' should point to 'index.md', thx to @gnaegi 52 | 53 | ## 1.0.5 (2023-09-18) 54 | 55 | - **plugin**: fix handling of files with dotted suffixes, thx to @gnaegi (#259) 56 | 57 | ## 1.0.4 (2023-09-18) 58 | 59 | - **assets**: Handle more assets, by Kamil Krzyśków 60 | - **plugin**: Fix build log info about directory, by Kamil Krzyśków 61 | - **utils**: Fix logging filter class name, by Kamil Krzyśków 62 | - **plugin**: Improve logging in general, by Kamil Krzyśków 63 | - **plugin**: Use new filter to hide log duplicates, by Kamil Krzyśków 64 | 65 | ## 1.0.3 (2023-09-07) 66 | 67 | - **plugin**: add support for --dirty and --dirtyreload (#249), by AngryMane 68 | - **plugin**: fix and improve reconfigure_search_duplicates (#253), by AngryMane 69 | - **ci(github)**: add docs build test and deploy on push to main 70 | 71 | ## 1.0.2 (2023-08-29) 72 | 73 | - **plugin**: on_page_context providing wrong page context data 74 | 75 | ## 1.0.1 (2023-08-29) 76 | 77 | - **reconfigure**: base_url should handle non mandatory site_url config 78 | 79 | ## 1.0.0 (2023-08-28) 80 | 81 | Major rewrite with breaking changes [as described and explained in this PR](https://github.com/ultrabug/mkdocs-static-i18n/pull/216). 82 | 83 | I want to thank [Kamil Krzyśków](https://github.com/kamilkrzyskow) for his major contribution in fostering this breakthrough, his numerous direct contributions and PRs and all the time he dedicated in providing feedbacks. 84 | 85 | A special mention to [@unverbuggt](https://github.com/unverbuggt) as well who's given the last boost of energy and feedbacks I needed to get this 1.0.0 version out! -------------------------------------------------------------------------------- /docs/getting-started/installation.md: -------------------------------------------------------------------------------- 1 | # Installation 2 | 3 | Add `mkdocs-static-i18n` to your `pyproject.toml` or `requirements.txt` file or simply install it using `pip`. The plugin will automatically install the minimally required version of `mkdocs` it is compatible with. 4 | 5 | ```bash 6 | pip install mkdocs-static-i18n 7 | ``` 8 | 9 | *It is advised to pin the version of the plugin if you're wary of forward breaking changes*. 10 | 11 | Optionally, you can install the plugin with its compatible minimal version of `mkdocs-material` if you're using it too, like so: 12 | 13 | ```bash 14 | pip install mkdocs-static-i18n[material] 15 | ``` 16 | -------------------------------------------------------------------------------- /docs/getting-started/philosophy.md: -------------------------------------------------------------------------------- 1 | # Philosophy 2 | 3 | I created this plugin after [bringing internationalization (i18n) support to MkDocs](https://github.com/mkdocs/mkdocs/pull/2299). Once themes could be translated, it was time to help authors (you) localize their pages' content! 4 | 5 | Since translating content is a cumbersome task I tried (hard) to remove as much boilerplate as possible for authors and translators as possible. This materialized in features like automatic localization of content so that you can localize assets such as images without having to care about their localized name and use the same reference in your MarkDown source whatever the language! 6 | 7 | This plugin will do its best to provide best in class support for `mkdocs-material` users as well as some other plugins which are listed in the compatibility section of this documentation. 8 | 9 | I hope you get a smooth and satisfying experience in using this plugin, enjoy! 10 | -------------------------------------------------------------------------------- /docs/getting-started/quick-start.md: -------------------------------------------------------------------------------- 1 | # Quick Start 2 | 3 | !!! warning 4 | This documentation applies from `mkdocs-static-i18n` **version 1.0.0**. 5 | Users of older versions should check the [previous version 0.56 documentation](https://github.com/ultrabug/mkdocs-static-i18n/tree/0.56#readme). 6 | 7 | After you [installed](installation.md) the plugin there are a few steps to get started. 8 | 9 | ## Choose your localization docs structure 10 | 11 | This plugin allows you to choose how you're going to organize your localized pages. 12 | 13 | - Using the `suffix` docs structure (default), you will suffix your files with `..` (like `index.fr.md`) 14 | - Using the `folder` docs structure, you will create a folder per language code (like `en/` and `fr/`) and put your localized pages on those folders 15 | 16 | Below is an example of both structures, whichever you choose is up to you, they will produce the same output. 17 | 18 | ### The suffix docs structure (default) 19 | 20 | ```text 21 | ./docs_suffix_structure 22 | ├── assets 23 | │   └── image_non_localized.png 24 | ├── image.en.png 25 | ├── image.fr.png 26 | ├── index.fr.md 27 | ├── index.en.md 28 | ├── topic1 29 | │   ├── index.en.md 30 | │   └── index.fr.md 31 | └── topic2 32 | │   ├── index.en.md 33 | │   └── index.fr.md 34 | ``` 35 | 36 | ### The folder docs structure 37 | 38 | ```text 39 | ./docs_folder_structure 40 | ├── assets 41 | │   └── image_non_localized.png 42 | ├── en 43 | │   ├── image.png 44 | │   ├── index.md 45 | │   ├── topic1 46 | │   │   └── index.md 47 | │   └── topic2 48 | │   └── index.md 49 | └── fr 50 | ├── image.png 51 | ├── index.md 52 | ├── topic1 53 | │   └── index.md 54 | └── topic2 55 | └── index.md 56 | ``` 57 | 58 | ## Configure the plugin in your mkdocs.yml 59 | 60 | Once you know which structure (here we choose `suffix`) you'll use, add the plugin with its minimal configuration to support your expected languages while **choosing a default language**. 61 | 62 | Don't worry about missing pages in the non-default language (here `fr`): they will use the default version (`en`) by default (this is configurable using the `fallback_to_default` option). 63 | 64 | ```yaml 65 | plugins: 66 | - i18n: 67 | docs_structure: suffix 68 | languages: 69 | - locale: en 70 | default: true 71 | name: English 72 | build: true 73 | - locale: fr 74 | name: Français 75 | build: true 76 | ``` 77 | 78 | ## Build and test your localized site 79 | 80 | Congratulations, you're ready to watch your localized site live as the plugin will generate an URL path for each language: 81 | 82 | - The default (`en`) language will reside in the root URL `/` 83 | - The French localized (`fr`) language will reside in the `fr` URL `/fr/` 84 | 85 | ```bash 86 | mkdocs serve 87 | ``` 88 | 89 | The plugin will generate the following `site` structure: 90 | 91 | ```text 92 | site 93 | ├── 404.html 94 | ├── assets 95 | │   ├── image_non_localized.png 96 | 97 | [...] 98 | 99 | ├── fr 100 | │   ├── image.png 101 | │   ├── index.html 102 | │   ├── topic1 103 | │   │   └── index.html 104 | │   └── topic2 105 | │   └── index.html 106 | ├── image.png 107 | ├── index.html 108 | ├── search 109 | │   └── search_index.json 110 | ├── sitemap.xml 111 | ├── sitemap.xml.gz 112 | ├── topic1 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /docs/index.fr.md: -------------------------------------------------------------------------------- 1 | --- 2 | template: home.fr.html 3 | title: MkDocs static i18n plugin 4 | --- 5 | 6 | # MkDocs static i18n plugin 7 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | template: home.html 3 | title: MkDocs static i18n plugin 4 | --- 5 | 6 | # MkDocs static i18n plugin 7 | -------------------------------------------------------------------------------- /docs/overrides/home.fr.html: -------------------------------------------------------------------------------- 1 | {% extends "main.html" %} 2 | {% block tabs %} 3 | {{ super() }} 4 | 23 |
24 |
25 |
26 |
27 | 28 |
29 |
30 |

Localiser un site MkDocs facilement

31 |

Le plugin mkdocs-static-i18n vous permet de rendre votre documentation disponible dans plusieurs langues en ajoutant des versions traduites de vos pages et contenus à votre structure actuelle.

32 |

Ce plugin est pensé pour être le plus simple possible et il va générer une version par défaut de votre site + une version par langue configurée dans leur chemin respectif <langue>/.

33 |

Si ce n'est pas suffisant, mkdocs-static-i18n va aussi vous permettre de générer et mettre à disposition des versions localisées de n'importe quel type de fichier afin d'afficher des images, médias ou autre ressource dans le contexte de leur langue tout en permttant d'afficher la version par défaut si besoin.

34 |

Concentrez-vous sur les traductions, pas sur le travail rébarbatif de mise à jour de tous les liens et références pour chaque langue!

35 | 36 | Démarrage Rapide 37 | 38 | 39 | Configuration 40 | 41 |
42 |
43 |
44 |
45 | {% endblock %} 46 | {% block content %}{% endblock %} 47 | {% block footer %}{% endblock %} -------------------------------------------------------------------------------- /docs/overrides/home.html: -------------------------------------------------------------------------------- 1 | {% extends "main.html" %} 2 | {% block tabs %} 3 | {{ super() }} 4 | 23 |
24 |
25 |
26 |
27 | 28 |
29 |
30 |

MkDocs site localization made easy

31 |

The mkdocs-static-i18n plugin allows you to support multiple languages of your documentation by adding static translation files to your existing documentation pages.

32 |

This plugin is made to be as simple as possible and will generate a default version of your website + one version per configured language on their corresponding <language>/ path.

33 |

Even better, mkdocs-static-i18n also allows you to build and serve localized versions of any file extension to display localized images, medias and assets with support to automatic fallback to the default language pages and resources.

34 |

Focus on translations, not in assets and resources links updates for each localized language!

35 | 36 | Quick Start 37 | 38 | 39 | Configuration 40 | 41 |
42 |
43 |
44 |
45 | {% endblock %} 46 | {% block content %}{% endblock %} 47 | {% block footer %}{% endblock %} -------------------------------------------------------------------------------- /docs/overrides/partials/copyright.html: -------------------------------------------------------------------------------- 1 |
2 | {% if config.copyright %} 3 |
4 | {{ config.copyright }} 5 |
6 | {% endif %} 7 | {% if not config.extra.generator == false %} 8 | Made with 9 | 10 | Material for MkDocs 11 | 12 | and localized using the 13 | 14 | MkDocs Static i18n Plugin 15 | 16 | {% endif %} 17 |
-------------------------------------------------------------------------------- /docs/setup/choosing-the-structure.md: -------------------------------------------------------------------------------- 1 | # Choosing the docs structure 2 | 3 | Depending on your project size and personal taste, you are free to choose a `docs/` structure that will allow you to organize your localized pages and resources using the `docs_structure` configuration option. 4 | 5 | ## Option: `docs_structure` 6 | 7 | |required|default|allowed values| 8 | |---|---|---| 9 | |yes|suffix| suffix \| folder| 10 | 11 | ``` yaml 12 | plugins: 13 | - i18n: 14 | docs_structure: suffix 15 | ``` 16 | 17 | ## The suffix structure 18 | 19 | Using the `suffix` docs structure (default), you will suffix your files with `..` (like `index.fr.md`). 20 | 21 | ``` 22 | ./docs_suffix_structure 23 | ├── assets 24 | │   └── image_non_localized.png 25 | ├── image.en.png 26 | ├── image.fr.png 27 | ├── index.fr.md 28 | ├── index.en.md 29 | ├── topic1 30 | │   ├── index.en.md 31 | │   └── index.fr.md 32 | └── topic2 33 | │   ├── index.en.md 34 | │   └── index.fr.md 35 | ``` 36 | 37 | ## The folder structure 38 | 39 | Using the `folder` docs structure, you will create a folder per language code (like `en/` and `fr/`) and put your localized pages on those folders. 40 | 41 | ``` 42 | ./docs_folder_structure 43 | ├── assets 44 | │   └── image_non_localized.png 45 | ├── en 46 | │   ├── image.png 47 | │   ├── index.md 48 | │   ├── topic1 49 | │   │   └── index.md 50 | │   └── topic2 51 | │   └── index.md 52 | └── fr 53 | ├── image.png 54 | ├── index.md 55 | ├── topic1 56 | │   └── index.md 57 | └── topic2 58 | └── index.md 59 | ``` -------------------------------------------------------------------------------- /docs/setup/index.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | The `mkdocs-static-i18n` plugin offers a flexible set of options to help you localize your site as smoothly as possible. 4 | 5 | This section contains all the details you need to succesfully get your localized site going. 6 | 7 | !!! warning 8 | This documentation applies from `mkdocs-static-i18n` **version 1.0.0**. 9 | Users of older versions should check the [previous version 0.56 documentation](https://github.com/ultrabug/mkdocs-static-i18n/tree/0.56#readme). 10 | 11 | ## Main configuration options overview 12 | 13 | |option|section| 14 | |---|---| 15 | |docs_structure|[Choosing the docs structure](choosing-the-structure.md)| 16 | |languages|[Setting up languages](setting-up-languages.md)| 17 | |fallback_to_default|[Controlling your builds](controlling-your-builds.md)| 18 | |reconfigure_material|[Setting up mkdocs-material](setting-up-material.md)| 19 | |reconfigure_search|[Setting up search](setting-up-search.md)| 20 | 21 | ## MkDocs events priority matrix 22 | 23 | This plugin uses MkDocs event priority in order to reconfigure each of the build process steps at the less instrusive time possible to other plugins. 24 | 25 | |build event|priority| 26 | |---|---| 27 | |on_config|-100| 28 | |on_files|-100| 29 | |on_nav|-100| 30 | |on_env|0| 31 | |on_template_context|50| 32 | |on_page_markdown|50| 33 | |on_page_context|50| 34 | |on_post_page|-100| 35 | |on_post_build|-100| 36 | 37 | ## Configuration example 38 | 39 | This very documentation is built using the plugin, so it might be interesting to you [to check its mkdocs.yml](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml)! 40 | -------------------------------------------------------------------------------- /docs/setup/localizing-navigation.md: -------------------------------------------------------------------------------- 1 | # Localizing navigation 2 | 3 | You can easily translate navigation items or override the whole navigation per language. 4 | 5 | !!! tip 6 | The `mkdocs-static-i18n` plugin takes care of selecting the right file for you **so you never have to use their localized name**! 7 | 8 | Just use your page expected names (`index.md`, not `index.fr.md`) as you would on a single language site. 9 | 10 | ## Translating navigation items 11 | 12 | This sub-option is a key/value mapping set per language as allows you to override the title of any navigation item when a matching title exists on the default language. 13 | 14 | ### Language Sub-Option: `nav_translations` 15 | 16 | This example will translate the `Home`, `Topic1` and `Topic2` section titles to `Accueil`, `Sujet1` and `Sujet2` in the French version of the site. 17 | 18 | ``` yaml 19 | nav: 20 | - Home: index.md 21 | - Topic1: topic1/index.md 22 | - Topic2: topic2/index.md 23 | 24 | plugins: 25 | - i18n: 26 | languages: 27 | - locale: en 28 | default: true 29 | name: English 30 | - locale: fr 31 | name: Français 32 | nav_translations: 33 | Home: Accueil 34 | Topic1: Sujet1 Traduit 35 | Topic2: Sujet2 Traduit 36 | ``` 37 | 38 | ## Overriding the navigation per language 39 | 40 | This sub-option allows to override the whole `nav` configuration option of your `mkdocs.yml` per language. This allows to have a completely separate navigation per language! 41 | 42 | ### Language Sub-Option: `nav` 43 | 44 | This example overrides the navigation of the French version of the site. **Mind the fact that we do not need to localize the path or file names**! 45 | 46 | ``` yaml 47 | nav: 48 | - Home: index.md 49 | - Topic1: topic1/index.md 50 | - Topic2: topic2/index.md 51 | 52 | plugins: 53 | - i18n: 54 | languages: 55 | - locale: en 56 | default: true 57 | name: English 58 | - locale: fr 59 | name: Français 60 | nav: 61 | - Premiere Section: topic1/index.md 62 | - Accueil: index.md 63 | ``` 64 | -------------------------------------------------------------------------------- /docs/setup/plugins-compatibility.md: -------------------------------------------------------------------------------- 1 | # Interfacing with other plugins 2 | 3 | While the `mkdocs-static-i18n` plugin does its best to be smart about its build process logic manipulation it can't possibly be aware of every other MkDocs plugin constraints. 4 | 5 | This is a list of plugins known to work with `mkdocs-static-i18n`: 6 | 7 | |plugin|compatible version| 8 | |---|---| 9 | |mkdocs-material|>=9.2.3| 10 | |mkdocs-awesome-pages|>=2.9.1| 11 | |mkdocs-redirects|>=1.2.1| 12 | |mkdocs-rss-plugin|>=1.8.0| 13 | |mkdocs-with-pdf|>=0.9.3| 14 | 15 | If the list is not correct or that you would like another plugin to be made compatible: 16 | 17 | - make a sample repository available with the right `requirements.txt` and `mkdocs.yml` so that we can reproduce your problem 18 | - [open an issue](https://github.com/ultrabug/mkdocs-static-i18n/issues) and explain your use case + link the repository you've created 19 | -------------------------------------------------------------------------------- /docs/setup/setting-up-material.md: -------------------------------------------------------------------------------- 1 | # Setting up mkdocs-material 2 | 3 | The `mkdocs-static-i18n` plugin aims at providing best-in-class support to the [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) theme and plugins users! 4 | 5 | As such, it will do its best to automagically adjust the `mkdocs-material` theme configuration per language such as its `lang` and `extra.alternates` language switcher. 6 | 7 | !!! tip 8 | The `mkdocs-material` language switcher will also benefit from the [alternate awareness of the plugin](using-alternates.md) as it will contextualize the links of the language switcher to point to the language alternates of the current page instead of just pointing to the root the each configured language. 9 | 10 | This will smoothen your users' experience as they will be able to switch from one language to another on the same page! 11 | 12 | This feature is controlled by the `reconfigure_material` option and you can [personalize your language builds even further using the languages options](setting-up-languages.md). 13 | 14 | ## Option: `reconfigure_material` 15 | 16 | |required|default|allowed values| 17 | |---|---|---| 18 | |no|true| true \| false| 19 | 20 | ``` yaml 21 | plugins: 22 | - i18n: 23 | reconfigure_material: true 24 | ``` 25 | 26 | ## Adding a special item in the language switcher 27 | 28 | If you want to add a special item in the automatically generated language switcher pointing to a fixed link, use the special `"null"` (quotes intended) locale. 29 | 30 | ``` yaml 31 | plugins: 32 | - i18n: 33 | languages: 34 | - locale: en 35 | name: English 36 | build: true 37 | default: true 38 | - locale: fr 39 | name: Français 40 | build: true 41 | - locale: "null" 42 | name: Help translating 43 | build: false 44 | fixed_link: https://spaceship-prompt.sh/contribute/?h=trans#Translating 45 | ``` 46 | 47 | ![spaceship prompt help translating](../assets/spaceship_help_translating_item.png){width=450} 48 | 49 | ## Features 50 | 51 | !!! failure "Incompatibility" 52 | The `navigation.instant` feature is **NOT compatible** with the multi-language switcher. The plugin will issue a WARNING log if you try using it. 53 | 54 | - [x] Automatic language setup 55 | - [x] Automatic language switcher setup 56 | - [x] Automatic language switcher contextual link setup 57 | - [x] Search plugin localization and result deduplication 58 | - [ ] Blog plugin localization 59 | -------------------------------------------------------------------------------- /docs/setup/setting-up-search.md: -------------------------------------------------------------------------------- 1 | # Setting up search 2 | 3 | When using the `search` or `material/search` plugin, the `reconfigure_search` option allows you to control whether you want the plugin to remove duplicate content from your search results. 4 | 5 | This is especially useful if you have non-localized content along with the `fallback_to_default: true` option set as some of your language content will be copied over to language specific paths and added to the search results (which would cause duplicate results). 6 | 7 | ## Option: `reconfigure_search` 8 | 9 | |required|default|allowed values| 10 | |---|---|---| 11 | |no|true| true \| false| 12 | 13 | ``` yaml 14 | plugins: 15 | - i18n: 16 | reconfigure_search: true 17 | ``` 18 | -------------------------------------------------------------------------------- /docs/setup/translating-content.md: -------------------------------------------------------------------------------- 1 | # Translating content 2 | 3 | **Focus on translating your content**, not on updating all the links and references to your files! 4 | 5 | Let `mkdocs-static-i18n` do the heavy lifting of dynamically localizing your assets and just reference everything without their localized extension. 6 | 7 | Since the generated `site` files have their localization extension removed during the build process, you **must** reference them in your markdown source without it (this includes links to `.md` files)! 8 | 9 | This simple docs structure: 10 | 11 | ``` 12 | docs 13 | ├── image.en.png 14 | ├── image.fr.png 15 | ├── index.fr.md 16 | ├── index.md 17 | ``` 18 | 19 | Will generate this site tree: 20 | 21 | ``` 22 | site 23 | ├── fr 24 | │   ├── image.png 25 | │   ├── index.html 26 | ├── image.png 27 | ├── index.html 28 | ``` 29 | 30 | Which means that the `image.png` and its `fr/image.png` localized counterpart can be referenced the same way as `![my image](image.png)` on both `index.md` and `index.fr.md` when using the `suffix` docs structure. 31 | 32 | It works the same for the `folder` structure! 33 | 34 | !!! tip 35 | You may find useful to inform users that some pages are not translated (yet) by [injecting content on an announcement block](https://github.com/ultrabug/mkdocs-static-i18n/issues/276#issuecomment-1785900709) when a page is displayed using its fallback language and thus missing a translation. 36 | 37 | ## Translating admonitions 38 | 39 | This sub-option is a key/value mapping set per language and allows you to translate [admonition](https://python-markdown.github.io/extensions/admonition/) titles which don't have an explicit title defined. 40 | 41 | Also, this configuration will apply to [PyMdown Details Extension][details], if the extension is enabled. 42 | 43 | [details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/ 44 | 45 | ### Language Sub-Option: `admonition_translations` 46 | 47 | This example overrides admonition titles of the French version of the site. 48 | 49 | ``` yaml 50 | plugins: 51 | - i18n: 52 | languages: 53 | - locale: en 54 | default: true 55 | name: English 56 | - locale: fr 57 | name: Français 58 | admonition_translations: 59 | - tip: Conseil 60 | - warning: Avertissement 61 | 62 | markdown_extensions: 63 | - admonition 64 | - pymdownx.details 65 | ``` 66 | 67 | and translates French markdowns: 68 | 69 | === "admonitions" 70 | From: 71 | 72 | ``` 73 | !!! tip 74 | 75 | Bonjour le monde 76 | ``` 77 | 78 | to: 79 | 80 | ``` 81 | !!! tip "Conseil" 82 | 83 | Bonjour le monde 84 | ``` 85 | 86 | === "details" 87 | From: 88 | 89 | ``` 90 | ??? tip 91 | 92 | Bonjour le monde 93 | ``` 94 | 95 | to: 96 | 97 | ``` 98 | ??? tip "Conseil" 99 | 100 | Bonjour le monde 101 | ``` 102 | 103 | === "details (open)" 104 | From: 105 | 106 | ``` 107 | ???+ tip 108 | 109 | Bonjour le monde 110 | ``` 111 | 112 | to: 113 | 114 | ``` 115 | ???+ tip "Conseil" 116 | 117 | Bonjour le monde 118 | ``` 119 | -------------------------------------------------------------------------------- /docs/setup/upgrading-to-1.md: -------------------------------------------------------------------------------- 1 | # Upgrading to 1.0.0 2 | 3 | Already a `mkdocs-static-i18n` plugin user? Thank you! :hugging: 4 | 5 | The plugin's configuration changed quite a lot since the previous version so I wrote [a migration script](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/config_update_to_v1.py) that you just need to point to your current `mkdocs.yml` file and that will output the desired v1.0.0 YAML configuration for you! 6 | 7 | ```bash 8 | python config_update_to_v1.py /path/to/mkdocs.yml 9 | ``` 10 | -------------------------------------------------------------------------------- /docs/setup/using-alternates.md: -------------------------------------------------------------------------------- 1 | # Using i18n alternates 2 | 3 | The `mkdocs-static-i18n` plugin keeps track of every page alternate and makes this information available to template builders: 4 | 5 | - `i18n_build_languages`: list of the language locales with `build: true` 6 | - `i18n_current_language_config`: locale specific configuration of the language currently building 7 | - `i18n_current_language`: locale of the language currently building 8 | - `i18n_alternates`: locale/Files (from mkdocs.structure.files) mapping used to build the sitemap.xml 9 | 10 | ## Localized sitemap 11 | 12 | Since version 0.32 the plugin provides a template that will generate automatically an alternate aware `sitemap.xml` so that your localized content is made available to search engines! 13 | 14 | Check out the [localization aware sitemap.xml](/mkdocs-static-i18n/sitemap.xml) of this documentation! 15 | 16 | ```xml 17 | 18 | 19 | 20 | https://ultrabug.github.io/mkdocs-static-i18n/ 21 | 2023-08-25 22 | daily 23 | 24 | 25 | 26 | 27 | 28 | https://ultrabug.github.io/mkdocs-static-i18n/getting-started/installation/ 29 | 2023-08-25 30 | daily 31 | 32 | 33 | 34 | 35 | 36 | https://ultrabug.github.io/mkdocs-static-i18n/getting-started/philosophy/ 37 | 2023-08-25 38 | daily 39 | 40 | 41 | 42 | 43 | 44 | ... 45 | 46 | 47 | ``` 48 | -------------------------------------------------------------------------------- /docs/setup/using-i18n-context.md: -------------------------------------------------------------------------------- 1 | # Using i18 context variables 2 | 3 | The plugin exports some useful i18n variables that you can access through the page context: 4 | 5 | - `i18n_config`: the i18n plugin configuration 6 | - `i18n_file_locale`: the locale of the source file used to build the page 7 | - `i18n_page_locale`: the current rendering locale of the page 8 | 9 | Those context [variables can be accessed using Jinja2 notation](https://jinja.palletsprojects.com/en/latest/templates/#variables), like `{{ i18n_page_locale }}` in your theme overrides. 10 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: MkDocs static i18n plugin documentation 2 | site_url: https://ultrabug.github.io/mkdocs-static-i18n 3 | repo_url: https://github.com/ultrabug/mkdocs-static-i18n 4 | 5 | docs_dir: docs/ 6 | exclude_docs: overrides/ 7 | 8 | copyright: Copyright © 2021-2023 Alexys Jacob 9 | 10 | theme: 11 | name: material 12 | font: false 13 | custom_dir: docs/overrides 14 | logo: 15 | assets/logo_by_maxicons.png 16 | palette: 17 | primary: blue 18 | features: 19 | - navigation.expand 20 | - navigation.indexes 21 | - navigation.sections 22 | - navigation.tabs 23 | - toc.follow 24 | - toc.integrate 25 | 26 | extra: 27 | social: 28 | - icon: fontawesome/brands/github 29 | link: https://github.com/ultrabug/mkdocs-static-i18n 30 | name: mkdocs-static-i18n on Github 31 | 32 | markdown_extensions: 33 | - admonition 34 | - attr_list 35 | - pymdownx.highlight: 36 | anchor_linenums: true 37 | - pymdownx.superfences 38 | - pymdownx.tasklist: 39 | custom_checkbox: true 40 | - pymdownx.tabbed: 41 | alternate_style: true 42 | - pymdownx.emoji: 43 | emoji_index: !!python/name:material.extensions.emoji.twemoji 44 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 45 | 46 | nav: 47 | - Home: index.md 48 | - Getting Started: 49 | - getting-started/installation.md 50 | - getting-started/quick-start.md 51 | - getting-started/philosophy.md 52 | - Configuration: 53 | - setup/index.md 54 | - setup/choosing-the-structure.md 55 | - setup/setting-up-languages.md 56 | - setup/translating-content.md 57 | - setup/controlling-your-builds.md 58 | - setup/localizing-navigation.md 59 | - setup/using-i18n-context.md 60 | - setup/using-alternates.md 61 | - setup/upgrading-to-1.md 62 | - Plugins Compatibility: 63 | - setup/setting-up-material.md 64 | - setup/setting-up-search.md 65 | - setup/plugins-compatibility.md 66 | - Changelog: changelog.md 67 | 68 | plugins: 69 | - search 70 | - i18n: 71 | docs_structure: suffix 72 | fallback_to_default: true 73 | reconfigure_material: true 74 | reconfigure_search: true 75 | languages: 76 | - locale: en 77 | default: true 78 | name: English 79 | build: true 80 | site_name: "MkDocs static i18n plugin documentation (en)" 81 | - locale: fr 82 | name: Français 83 | build: true 84 | site_name: "Documentation du plugin MkDocs static i18n (fr)" 85 | theme: 86 | palette: 87 | primary: red 88 | nav_translations: 89 | Home: Accueil 90 | Getting Started: Démarrage Rapide 91 | Plugins Compatibility: Compatibilité des plugins 92 | -------------------------------------------------------------------------------- /mkdocs_static_i18n/__init__.py: -------------------------------------------------------------------------------- 1 | from pathlib import PurePath 2 | 3 | version = "1.3.0" 4 | 5 | 6 | def is_relative_to(src_path, dest_path): 7 | try: 8 | return PurePath(src_path).is_relative_to(dest_path) 9 | except AttributeError: 10 | # python < 3.9 compat 11 | try: 12 | PurePath(src_path).relative_to(dest_path) 13 | return True 14 | except ValueError: 15 | return False 16 | -------------------------------------------------------------------------------- /mkdocs_static_i18n/custom_i18n_sitemap/sitemap.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | {%- for locale, i18n_files in i18n_alternates.items() %} 5 | 6 | {%- for file in i18n_files %} 7 | {%- if file.page.is_link %} 8 | {%- continue %} 9 | {%- endif %} 10 | 11 | {%- if not file.page %} 12 | {%- continue %} 13 | {%- endif %} 14 | 15 | {%- if file.page.canonical_url %} 16 | {%- set page_href = file.page.canonical_url | e %} 17 | {%- elif file.page.abs_url %} 18 | {%- set page_href = file.page.abs_url | e %} 19 | {%- else %} 20 | {%- set page_href = config.site_url ~ file.url %} 21 | {%- endif %} 22 | 23 | {#- 24 | Warning! Don't align the XML tags based on the Jinja2 statements. 25 | It will cause whitespace misalignment in the output. 26 | #} 27 | 28 | {{ page_href }} 29 | {%- if file.page.update_date %} 30 | {{ file.page.update_date }} 31 | {%- endif %} 32 | daily 33 | {%- for i18n_locale, i18n_file in file.alternates.items() %} 34 | 35 | {%- if i18n_file.page.canonical_url %} 36 | {%- set i18n_href = i18n_file.page.canonical_url | e %} 37 | {%- elif i18n_file.page.abs_url %} 38 | {%- set i18n_href = i18n_file.page.abs_url | e %} 39 | {%- else %} 40 | {%- if i18n_file.url == "./" %} 41 | {%- set i18n_href = config.site_url %} 42 | {%- else %} 43 | {%- set i18n_href = config.site_url ~ i18n_file.url %} 44 | {%- endif %} 45 | {%- endif %} 46 | 47 | {%- endfor %} 48 | 49 | {%- endfor %} 50 | {%- endfor %} 51 | 52 | -------------------------------------------------------------------------------- /mkdocs_static_i18n/utils.py: -------------------------------------------------------------------------------- 1 | """Utility functions and classes that aren't limited to any scenario.""" 2 | 3 | import logging 4 | from typing import Dict, Optional, TypeVar 5 | 6 | from mkdocs.config.defaults import MkDocsConfig 7 | from mkdocs.plugins import BasePlugin 8 | 9 | Plugin = TypeVar("Plugin", bound=BasePlugin) 10 | """Plugin Instance Type""" 11 | 12 | 13 | def get_plugin(name: str, config: MkDocsConfig) -> Optional[Plugin]: 14 | """Returns a plugin instance""" 15 | 16 | plugins: Dict[str, BasePlugin] = config["plugins"] 17 | instance: Plugin = plugins.get(name) 18 | 19 | if instance: 20 | return instance 21 | 22 | scoped_name: str = f"/{name}" 23 | 24 | # If the plugin was not found using the name 25 | # then look for a theme-namespaced plugin. 26 | for n, p in plugins.items(): 27 | if n.endswith(scoped_name): 28 | return p 29 | 30 | return None 31 | 32 | 33 | class I18nLoggingFilter: 34 | """Avoid logging duplicate build time messages.""" 35 | 36 | def __init__(self, *_, **__): 37 | self.filtered_prefixes = set() 38 | 39 | def __call__(self, record: logging.LogRecord) -> bool: 40 | for prefix in self.filtered_prefixes: 41 | if record.msg.startswith(prefix): 42 | return False 43 | 44 | return True 45 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["hatchling"] 3 | build-backend = "hatchling.build" 4 | 5 | [project] 6 | name = "mkdocs-static-i18n" 7 | dynamic = ["version"] 8 | description = "MkDocs i18n plugin using static translation markdown files" 9 | readme = "README.md" 10 | license = "MIT" 11 | requires-python = ">=3.8" 12 | authors = [ 13 | { name = "Ultrabug", email = "ultrabug@ultrabug.net" }, 14 | ] 15 | classifiers = [ 16 | "License :: OSI Approved :: MIT License", 17 | "Operating System :: POSIX :: Linux", 18 | "Programming Language :: Python", 19 | "Programming Language :: Python :: 3", 20 | "Programming Language :: Python :: 3 :: Only", 21 | "Programming Language :: Python :: 3.8", 22 | "Programming Language :: Python :: 3.9", 23 | "Programming Language :: Python :: 3.10", 24 | "Programming Language :: Python :: 3.11", 25 | "Programming Language :: Python :: 3.12", 26 | "Programming Language :: Python :: 3.13", 27 | "Topic :: Software Development :: Libraries :: Python Modules", 28 | ] 29 | dependencies = [ 30 | "mkdocs>=1.5.2", 31 | ] 32 | 33 | [project.entry-points."mkdocs.plugins"] 34 | i18n = "mkdocs_static_i18n.plugin:I18n" 35 | 36 | [project.urls] 37 | Documentation = "https://github.com/ultrabug/mkdocs-static-i18n#readme" 38 | Download = "https://github.com/ultrabug/mkdocs-static-i18n/tags" 39 | Funding = "https://ultrabug.fr/#support-me" 40 | Homepage = "https://github.com/ultrabug/mkdocs-static-i18n" 41 | Source = "https://github.com/ultrabug/mkdocs-static-i18n" 42 | Tracker = "https://github.com/ultrabug/mkdocs-static-i18n/issues" 43 | 44 | [tool.hatch.version] 45 | path = "mkdocs_static_i18n/__init__.py" 46 | 47 | [tool.hatch.build.targets.sdist] 48 | include = [ 49 | "/mkdocs_static_i18n", 50 | "/tests", 51 | ] 52 | [tool.hatch.build.targets.wheel] 53 | exclude = ["/tests"] 54 | 55 | [project.optional-dependencies] 56 | material = ["mkdocs-material>=9.2.5"] 57 | 58 | [tool.hatch.envs.default.scripts] 59 | all = [ 60 | "hatch run test:test", 61 | "hatch run style:check", 62 | ] 63 | 64 | [tool.hatch.envs.test] 65 | dependencies = [ 66 | "pytest", 67 | "mkdocs-material>=9.2.5" 68 | ] 69 | 70 | [tool.hatch.envs.test.scripts] 71 | test = [ 72 | "pytest -xs", 73 | ] 74 | 75 | [[tool.hatch.envs.test.matrix]] 76 | python = ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"] 77 | type = ["default"] 78 | 79 | [tool.hatch.envs.doc] 80 | dependencies = [ 81 | "mkdocs-material>=9.2.5" 82 | ] 83 | 84 | [tool.hatch.envs.doc.scripts] 85 | serve = [ 86 | "mkdocs serve", 87 | ] 88 | 89 | [tool.hatch.envs.style] 90 | detached = true 91 | dependencies = [ 92 | "black", 93 | "isort", 94 | "ruff", 95 | ] 96 | 97 | [tool.hatch.envs.style.scripts] 98 | check = [ 99 | "isort --check-only --diff mkdocs_static_i18n", 100 | "black -q --check --diff mkdocs_static_i18n", 101 | "ruff check mkdocs_static_i18n", 102 | ] 103 | format = [ 104 | "isort -q mkdocs_static_i18n", 105 | "black -q mkdocs_static_i18n", 106 | ] 107 | 108 | [tool.black] 109 | line-length = 100 110 | target-version = ["py313"] 111 | skip-string-normalization = true 112 | 113 | [tool.isort] 114 | profile = "black" 115 | line_length = 100 116 | 117 | [tool.ruff] 118 | line-length = 100 119 | 120 | [tool.ruff.lint] 121 | ignore = ["E501"] 122 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | """Installation using setup.py is no longer supported. 2 | Use `python -m pip install .` instead.""" 3 | 4 | import sys 5 | 6 | from setuptools import setup 7 | 8 | sys.exit(__doc__) 9 | 10 | # Fake reference so GitHub still considers it a real package for statistics purposes. 11 | setup( 12 | name="mkdocs-static-i18n", 13 | ) 14 | -------------------------------------------------------------------------------- /tests/admonitions/index.fr.md: -------------------------------------------------------------------------------- 1 | # Page d'accueil (french version) 2 | 3 | !!! tip 4 | Titre implicite dérivé du type d'avertissement, peut être remplacé en définissant `admonition_translations` 5 | 6 | !!!tip 7 | Pareil sans espaces 8 | 9 | !!! warning 10 | Titre implicite dérivé du type d'avertissement, peut être remplacé en définissant `admonition_translations` 11 | 12 | !!! warning "Heey" 13 | Titre explicite, n'est pas traduit par `admonition_translations` -------------------------------------------------------------------------------- /tests/admonitions/index.md: -------------------------------------------------------------------------------- 1 | # Home page 2 | 3 | !!! tip 4 | Implicit title derived from admonition type, can be overridden by setting `admonition_translations` 5 | 6 | !!!tip 7 | Same without space 8 | 9 | !!! warning 10 | Implicit title derived from admonition type, can be overridden by setting `admonition_translations` 11 | 12 | !!! warning "Heey" 13 | Explicit title, isn't translated by `admonition_translations` 14 | -------------------------------------------------------------------------------- /tests/conftest.py: -------------------------------------------------------------------------------- 1 | import pytest 2 | from mkdocs import utils 3 | from mkdocs.config.base import load_config 4 | from mkdocs.structure.files import get_files 5 | from mkdocs.structure.nav import get_navigation 6 | 7 | 8 | @pytest.fixture 9 | def make_config(): 10 | created_configs = [] 11 | 12 | def _make_config(mkdocs_fp=None, docs_dir=None, use_directory_urls=True, plugins={}): 13 | config = load_config( 14 | mkdocs_fp, 15 | docs_dir=docs_dir, 16 | theme={"name": "mkdocs"}, 17 | use_directory_urls=use_directory_urls, 18 | plugins=plugins, 19 | ) 20 | config = config.plugins.run_event("config", config) 21 | files = get_files(config) 22 | files = config.plugins.run_event("files", files, config=config) 23 | env = config.theme.get_env() 24 | nav = get_navigation(files, config) 25 | nav = config.plugins.run_event("nav", nav, files=files, config=config) 26 | # 27 | created_configs.append(config) 28 | # 29 | return config, files, env, nav 30 | 31 | yield _make_config 32 | 33 | for config in created_configs: 34 | utils.clean_directory(config.site_dir) 35 | 36 | 37 | @pytest.fixture 38 | def make_localized_config(make_config): 39 | created_configs = [] 40 | 41 | def _make_localized_config(config, locale): 42 | config.plugins["i18n"].current_language = locale 43 | # 44 | config = config.plugins.run_event("config", config) 45 | files = get_files(config) 46 | files = config.plugins.run_event("files", files, config=config) 47 | env = config.theme.get_env() 48 | nav = get_navigation(files, config) 49 | nav = config.plugins.run_event("nav", nav, files=files, config=config) 50 | # 51 | created_configs.append(config) 52 | # 53 | return config, files, env, nav 54 | 55 | yield _make_localized_config 56 | 57 | for config in created_configs: 58 | utils.clean_directory(config.site_dir) 59 | -------------------------------------------------------------------------------- /tests/details/index.fr.md: -------------------------------------------------------------------------------- 1 | # Page d'accueil (french version) 2 | 3 | ??? tip 4 | Titre implicite dérivé du type d'avertissement, peut être remplacé en définissant `admonition_translations` 5 | 6 | ???tip 7 | Pareil sans espaces 8 | 9 | ???+ tip 10 | Same but opened by default 11 | 12 | ???+tip 13 | Same without space 14 | 15 | ??? warning 16 | Titre implicite dérivé du type d'avertissement, peut être remplacé en définissant `admonition_translations` 17 | 18 | ??? warning "Heey" 19 | Titre explicite, n'est pas traduit par `admonition_translations` 20 | -------------------------------------------------------------------------------- /tests/details/index.md: -------------------------------------------------------------------------------- 1 | # Home page 2 | 3 | ??? tip 4 | Implicit title derived from admonition type, can be overridden by setting `admonition_translations` 5 | 6 | ???tip 7 | Same without space 8 | 9 | ???+ tip 10 | Same but opened by default 11 | 12 | ???+tip 13 | Same without space 14 | 15 | ??? warning 16 | Implicit title derived from admonition type, can be overridden by setting `admonition_translations` 17 | 18 | ??? warning "Heey" 19 | Explicit title, isn't translated by `admonition_translations` 20 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/assets/image_non_localized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_one_language/assets/image_non_localized.png -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/en/english_default/index.md: -------------------------------------------------------------------------------- 1 | # English default fallback 2 | 3 | This is the english version of a page that will show up on other languages as a fallback. 4 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/en/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_one_language/en/image.fake -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/en/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_one_language/en/image.png -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/en/index.md: -------------------------------------------------------------------------------- 1 | # Home page (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md <-- this file is used here 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image here on the /en version 31 | │   ├── index.html <-- you are here on the /en version 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html <-- you are here on the default version 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | Of course, images can also not be localized just like the image below which is 64 | used by all versions of your pages: 65 | 66 | ![non localized image](assets/image_non_localized.png) 67 | 68 | --- 69 | 70 | ## Localized build logic 71 | 72 | The settings used to build this site is: 73 | 74 | ``` 75 | plugins: 76 | - i18n: 77 | default_language: en 78 | languages: 79 | en: english 80 | fr: français 81 | ``` 82 | 83 | Meaning that we will get three versions of our website: 84 | 85 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 86 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 87 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 88 | 89 | Given that logic, the following `site` structure is built: 90 | 91 | ``` 92 | site 93 | ├── 404.html 94 | ├── assets 95 | │   ├── images 96 | │   ├── javascripts 97 | │   └── stylesheets 98 | ├── en 99 | │   ├── image.png 100 | │   ├── index.html 101 | │   ├── topic1 102 | │   │   └── named_file 103 | │   │   └── index.html 104 | │   └── topic2 105 | │   └── index.html 106 | ├── fr 107 | │   ├── image.png 108 | │   ├── index.html 109 | │   ├── topic1 110 | │   │   └── named_file 111 | │   │   └── index.html 112 | │   └── topic2 113 | │   └── index.html 114 | ├── image.png 115 | ├── index.html 116 | ├── topic1 117 | │   └── named_file 118 | │   └── index.html 119 | └── topic2 120 | └── index.html 121 | ``` 122 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/en/topic1/named_file.md: -------------------------------------------------------------------------------- 1 | # Topic 1 (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used on both the default and /en versions 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md <-- this file is used on both the default and /en versions 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image on the /en version 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html <-- you are here on the /en version 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html <-- you are here on the default version 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/en/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_one_language/en/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/en/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Topic 2 (english version + french version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used on the /en version 16 | ├── image.fr.png <-- this image file is used on the /fr version 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md <-- this file is used for both /en and /fr versions 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image on the /en version 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html <-- you are here on the /en version 37 | ├── fr 38 | │   ├── image.png <-- you see this image on the /fr version 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html <-- you are here on the /fr version 45 | ├── image.png 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/en/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_one_language/en/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/en/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_one_language/en/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/fr/french_only/index.md: -------------------------------------------------------------------------------- 1 | # This page only exists on the French version 2 | 3 | Et voilà ! -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/fr/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_one_language/fr/image.fake -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/fr/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_one_language/fr/image.png -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/fr/topic1/named_file.md: -------------------------------------------------------------------------------- 1 | # Sujet 1 (french version) 2 | 3 | !!! tip "Astuce" 4 | **Utilisez le sélecteur de langue dans la barre de titre** pour passer d'une version localisée à l'autre de ce site de démonstration. Ce sélecteur fait partie de [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) et est **configuré automatiquement par ce plugin** ou peut être défini de manière statique depuis le [fichier mkdocs.yml](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## Ce que vous voyez en ce moment 7 | 8 | La source de cette page et son contenu média ont été localisés en suivant la 9 | [logique de localisation](#logique-de-localisation) décrite ci-dessous. Voici 10 | un rapide récapitulatif des fichiers utilisés comme source et de la structure 11 | générée que vous voyez en ce moment: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png 16 | ├── image.fr.png <-- this image file is used on the /fr version 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md <-- this file is used on the /fr version 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png <-- you see this image on the /fr version 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html <-- you are here on the /fr version 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Localisation automatique des médias / liens / assets 55 | 56 | ![localized image](../image.png) 57 | 58 | La source de cette image est dynamiquement localisée bien qu'elle soit 59 | référencée dans la source du markdown par `![localized image](image.png)`. 60 | Cela démontre que ce plugin vous permet de ne pas vous préoccuper du nom 61 | des fichiers dans vos liens, médias et contenus statiques : utilisez leurs 62 | noms sans extension localisée et concentrez-vous sur la traduction de vos 63 | contenus ! 64 | 65 | --- 66 | 67 | ## Logique de localisation 68 | 69 | Ce site est construit avec cette configuration : 70 | 71 | ``` 72 | plugins: 73 | - i18n: 74 | default_language: en 75 | languages: 76 | en: english 77 | fr: français 78 | ``` 79 | 80 | Ce qui veut dire que nous obtiendrons trois versions de notre site : 81 | 82 | 1. la version `default_language` qui utilisera en premier les fichiers dont 83 | l'extension est `.md` et prendra quelconque fichier en `.en.md` en repli 84 | puisque la version `en` est configurée comme la langue par défaut 85 | 2. la version localisée `/en` qui utilisera les fichiers dont l'extension est 86 | `.en.md` en premier et utilisera leur version `.md` en repli si elle existe 87 | 3. la version localisée `/fr` qui utilisera les fichiers dont l'extension est 88 | `.fr.md` en premier et utilisera en repli soit la version `.en.md` (dérivée 89 | du langage par défaut) ou `.md` 90 | 91 | En suivant cette logique, la structure `site` générée est : 92 | 93 | ``` 94 | site 95 | ├── 404.html 96 | ├── assets 97 | │   ├── images 98 | │   ├── javascripts 99 | │   └── stylesheets 100 | ├── en 101 | │   ├── image.png 102 | │   ├── index.html 103 | │   ├── topic1 104 | │   │   └── named_file 105 | │   │   └── index.html 106 | │   └── topic2 107 | │   └── index.html 108 | ├── fr 109 | │   ├── image.png 110 | │   ├── index.html 111 | │   ├── topic1 112 | │   │   └── named_file 113 | │   │   └── index.html 114 | │   └── topic2 115 | │   └── index.html 116 | ├── image.png 117 | ├── index.html 118 | ├── topic1 119 | │   └── named_file 120 | │   └── index.html 121 | └── topic2 122 | └── index.html 123 | ``` 124 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/fr/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_one_language/fr/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/fr/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Topic 2 (default version only) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here on the default version 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md <-- this file is used here on the default version 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html <-- you are here on the default version 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/fr/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_one_language/fr/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/docs_folder_structure_one_language/fr/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_one_language/fr/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/assets/image_non_localized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages/assets/image_non_localized.png -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/en/english_default/index.md: -------------------------------------------------------------------------------- 1 | # English default fallback 2 | 3 | This is the english version of a page that will show up on other languages as a fallback. 4 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/en/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages/en/image.fake -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/en/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages/en/image.png -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/en/index.md: -------------------------------------------------------------------------------- 1 | # Home page (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md <-- this file is used here 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image here on the /en version 31 | │   ├── index.html <-- you are here on the /en version 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html <-- you are here on the default version 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | Of course, images can also not be localized just like the image below which is 64 | used by all versions of your pages: 65 | 66 | ![non localized image](assets/image_non_localized.png) 67 | 68 | --- 69 | 70 | ## Localized build logic 71 | 72 | The settings used to build this site is: 73 | 74 | ``` 75 | plugins: 76 | - i18n: 77 | default_language: en 78 | languages: 79 | en: english 80 | fr: français 81 | ``` 82 | 83 | Meaning that we will get three versions of our website: 84 | 85 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 86 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 87 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 88 | 89 | Given that logic, the following `site` structure is built: 90 | 91 | ``` 92 | site 93 | ├── 404.html 94 | ├── assets 95 | │   ├── images 96 | │   ├── javascripts 97 | │   └── stylesheets 98 | ├── en 99 | │   ├── image.png 100 | │   ├── index.html 101 | │   ├── topic1 102 | │   │   └── named_file 103 | │   │   └── index.html 104 | │   └── topic2 105 | │   └── index.html 106 | ├── fr 107 | │   ├── image.png 108 | │   ├── index.html 109 | │   ├── topic1 110 | │   │   └── named_file 111 | │   │   └── index.html 112 | │   └── topic2 113 | │   └── index.html 114 | ├── image.png 115 | ├── index.html 116 | ├── topic1 117 | │   └── named_file 118 | │   └── index.html 119 | └── topic2 120 | └── index.html 121 | ``` 122 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/en/topic1/named_file.md: -------------------------------------------------------------------------------- 1 | # Topic 1 (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used on both the default and /en versions 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md <-- this file is used on both the default and /en versions 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image on the /en version 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html <-- you are here on the /en version 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html <-- you are here on the default version 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/en/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages/en/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/en/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Topic 2 (english version + french version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used on the /en version 16 | ├── image.fr.png <-- this image file is used on the /fr version 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md <-- this file is used for both /en and /fr versions 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image on the /en version 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html <-- you are here on the /en version 37 | ├── fr 38 | │   ├── image.png <-- you see this image on the /fr version 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html <-- you are here on the /fr version 45 | ├── image.png 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/en/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages/en/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/en/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages/en/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/fr/french_only/index.md: -------------------------------------------------------------------------------- 1 | # This page only exists on the French version 2 | 3 | Et voilà ! -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/fr/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages/fr/image.fake -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/fr/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages/fr/image.png -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/fr/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages/fr/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages/fr/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Topic 2 (default version only) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here on the default version 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md <-- this file is used here on the default version 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html <-- you are here on the default version 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/assets/image_non_localized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages_with_default/assets/image_non_localized.png -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/en/english_default/index.md: -------------------------------------------------------------------------------- 1 | # English default fallback 2 | 3 | This is the english version of a page that will show up on other languages as a fallback. 4 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/en/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages_with_default/en/image.fake -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/en/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages_with_default/en/image.png -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/en/topic1/named_file.md: -------------------------------------------------------------------------------- 1 | # Topic 1 (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used on both the default and /en versions 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md <-- this file is used on both the default and /en versions 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image on the /en version 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html <-- you are here on the /en version 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html <-- you are here on the default version 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/en/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages_with_default/en/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/en/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Topic 2 (english version + french version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used on the /en version 16 | ├── image.fr.png <-- this image file is used on the /fr version 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md <-- this file is used for both /en and /fr versions 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image on the /en version 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html <-- you are here on the /en version 37 | ├── fr 38 | │   ├── image.png <-- you see this image on the /fr version 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html <-- you are here on the /fr version 45 | ├── image.png 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/en/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages_with_default/en/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/en/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages_with_default/en/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/fr/french_only/index.md: -------------------------------------------------------------------------------- 1 | # This page only exists on the French version 2 | 3 | Et voilà ! -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/fr/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages_with_default/fr/image.fake -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/fr/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages_with_default/fr/image.png -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/fr/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages_with_default/fr/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/fr/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Topic 2 (default version only) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here on the default version 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md <-- this file is used here on the default version 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html <-- you are here on the default version 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/fr/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages_with_default/fr/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/docs_folder_structure_two_languages_with_default/fr/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_folder_structure_two_languages_with_default/fr/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/assets/image_non_localized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_one_language/assets/image_non_localized.png -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/english_default/index.en.md: -------------------------------------------------------------------------------- 1 | # English default fallback 2 | 3 | This is the english version of a page that will show up on other languages as a fallback. 4 | -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/french_only/index.fr.md: -------------------------------------------------------------------------------- 1 | # This page only exists on the French version 2 | 3 | Et voilà ! -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/image.en.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_one_language/image.en.fake -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/image.en.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_one_language/image.en.png -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/image.fr.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_one_language/image.fr.fake -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/image.fr.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_one_language/image.fr.png -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/index.md: -------------------------------------------------------------------------------- 1 | # Home page (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md <-- this file is used here 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image here on the /en version 31 | │   ├── index.html <-- you are here on the /en version 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html <-- you are here on the default version 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | Of course, images can also not be localized just like the image below which is 64 | used by all versions of your pages: 65 | 66 | ![non localized image](assets/image_non_localized.png) 67 | 68 | --- 69 | 70 | ## Localized build logic 71 | 72 | The settings used to build this site is: 73 | 74 | ``` 75 | plugins: 76 | - i18n: 77 | default_language: en 78 | languages: 79 | en: english 80 | fr: français 81 | ``` 82 | 83 | Meaning that we will get three versions of our website: 84 | 85 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 86 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 87 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 88 | 89 | Given that logic, the following `site` structure is built: 90 | 91 | ``` 92 | site 93 | ├── 404.html 94 | ├── assets 95 | │   ├── images 96 | │   ├── javascripts 97 | │   └── stylesheets 98 | ├── en 99 | │   ├── image.png 100 | │   ├── index.html 101 | │   ├── topic1 102 | │   │   └── named_file 103 | │   │   └── index.html 104 | │   └── topic2 105 | │   └── index.html 106 | ├── fr 107 | │   ├── image.png 108 | │   ├── index.html 109 | │   ├── topic1 110 | │   │   └── named_file 111 | │   │   └── index.html 112 | │   └── topic2 113 | │   └── index.html 114 | ├── image.png 115 | ├── index.html 116 | ├── topic1 117 | │   └── named_file 118 | │   └── index.html 119 | └── topic2 120 | └── index.html 121 | ``` 122 | -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/topic1/named_file.en.md: -------------------------------------------------------------------------------- 1 | # Topic 1 (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used on both the default and /en versions 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md <-- this file is used on both the default and /en versions 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image on the /en version 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html <-- you are here on the /en version 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html <-- you are here on the default version 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/topic2/1.1.filename.fr.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_one_language/topic2/1.1.filename.fr.html -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_one_language/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/topic2/README.fr.md: -------------------------------------------------------------------------------- 1 | # Sujet 2 (french version) 2 | 3 | !!! tip "Astuce" 4 | **Utilisez le sélecteur de langue dans la barre de titre** pour passer d'une version localisée à l'autre de ce site de démonstration. Ce sélecteur fait partie de [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) et est **configuré automatiquement par ce plugin** ou peut être défini de manière statique depuis le [fichier mkdocs.yml](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## Ce que vous voyez en ce moment 7 | 8 | La source de cette page et son contenu média ont été localisés en suivant la 9 | [logique de localisation](#logique-de-localisation) décrite ci-dessous. Voici 10 | un rapide récapitulatif des fichiers utilisés comme source et de la structure 11 | générée que vous voyez en ce moment: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png 16 | ├── image.fr.png <-- this image file is used on the /fr version 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md <-- this file is used on the /fr version 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png <-- you see this image on the /fr version 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html <-- you are here on the /fr version 45 | ├── image.png 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Localisation automatique des médias / liens / assets 55 | 56 | ![localized image](../image.png) 57 | 58 | La source de cette image est dynamiquement localisée bien qu'elle soit 59 | référencée dans la source du markdown par `![localized image](image.png)`. 60 | Cela démontre que ce plugin vous permet de ne pas vous préoccuper du nom 61 | des fichiers dans vos liens, médias et contenus statiques : utilisez leurs 62 | noms sans extension localisée et concentrez-vous sur la traduction de vos 63 | contenus ! 64 | 65 | --- 66 | 67 | ## Logique de localisation 68 | 69 | Ce site est construit avec cette configuration : 70 | 71 | ``` 72 | plugins: 73 | - i18n: 74 | default_language: en 75 | languages: 76 | en: english 77 | fr: français 78 | ``` 79 | 80 | Ce qui veut dire que nous obtiendrons trois versions de notre site : 81 | 82 | 1. la version `default_language` qui utilisera en premier les fichiers dont 83 | l'extension est `.md` et prendra quelconque fichier en `.en.md` en repli 84 | puisque la version `en` est configurée comme la langue par défaut 85 | 2. la version localisée `/en` qui utilisera les fichiers dont l'extension est 86 | `.en.md` en premier et utilisera leur version `.md` en repli si elle existe 87 | 3. la version localisée `/fr` qui utilisera les fichiers dont l'extension est 88 | `.fr.md` en premier et utilisera en repli soit la version `.en.md` (dérivée 89 | du langage par défaut) ou `.md` 90 | 91 | En suivant cette logique, la structure `site` générée est : 92 | 93 | ``` 94 | site 95 | ├── 404.html 96 | ├── assets 97 | │   ├── images 98 | │   ├── javascripts 99 | │   └── stylesheets 100 | ├── en 101 | │   ├── image.png 102 | │   ├── index.html 103 | │   ├── topic1 104 | │   │   └── named_file 105 | │   │   └── index.html 106 | │   └── topic2 107 | │   └── index.html 108 | ├── fr 109 | │   ├── image.png 110 | │   ├── index.html 111 | │   ├── topic1 112 | │   │   └── named_file 113 | │   │   └── index.html 114 | │   └── topic2 115 | │   └── index.html 116 | ├── image.png 117 | ├── index.html 118 | ├── topic1 119 | │   └── named_file 120 | │   └── index.html 121 | └── topic2 122 | └── index.html 123 | ``` 124 | -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Topic 2 (default version only) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here on the default version 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md <-- this file is used here on the default version 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html <-- you are here on the default version 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_one_language/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/docs_suffix_structure_one_language/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_one_language/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/assets/image_non_localized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_two_languages/assets/image_non_localized.png -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/english_default/index.en.md: -------------------------------------------------------------------------------- 1 | # English default fallback 2 | 3 | This is the english version of a page that will show up on other languages as a fallback. 4 | -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/french_only/index.fr.md: -------------------------------------------------------------------------------- 1 | # This page only exists on the French version 2 | 3 | Et voilà ! -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/image.en.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_two_languages/image.en.fake -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/image.en.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_two_languages/image.en.png -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/image.fr.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_two_languages/image.fr.fake -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/image.fr.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_two_languages/image.fr.png -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/index.md: -------------------------------------------------------------------------------- 1 | # Home page (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md <-- this file is used here 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image here on the /en version 31 | │   ├── index.html <-- you are here on the /en version 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html <-- you are here on the default version 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | Of course, images can also not be localized just like the image below which is 64 | used by all versions of your pages: 65 | 66 | ![non localized image](assets/image_non_localized.png) 67 | 68 | --- 69 | 70 | ## Localized build logic 71 | 72 | The settings used to build this site is: 73 | 74 | ``` 75 | plugins: 76 | - i18n: 77 | default_language: en 78 | languages: 79 | en: english 80 | fr: français 81 | ``` 82 | 83 | Meaning that we will get three versions of our website: 84 | 85 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 86 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 87 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 88 | 89 | Given that logic, the following `site` structure is built: 90 | 91 | ``` 92 | site 93 | ├── 404.html 94 | ├── assets 95 | │   ├── images 96 | │   ├── javascripts 97 | │   └── stylesheets 98 | ├── en 99 | │   ├── image.png 100 | │   ├── index.html 101 | │   ├── topic1 102 | │   │   └── named_file 103 | │   │   └── index.html 104 | │   └── topic2 105 | │   └── index.html 106 | ├── fr 107 | │   ├── image.png 108 | │   ├── index.html 109 | │   ├── topic1 110 | │   │   └── named_file 111 | │   │   └── index.html 112 | │   └── topic2 113 | │   └── index.html 114 | ├── image.png 115 | ├── index.html 116 | ├── topic1 117 | │   └── named_file 118 | │   └── index.html 119 | └── topic2 120 | └── index.html 121 | ``` 122 | -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/topic1/named_file.en.md: -------------------------------------------------------------------------------- 1 | # Topic 1 (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used on both the default and /en versions 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md <-- this file is used on both the default and /en versions 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image on the /en version 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html <-- you are here on the /en version 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html <-- you are here on the default version 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/topic2/1.1.filename.fr.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_two_languages/topic2/1.1.filename.fr.html -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_two_languages/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/topic2/README.fr.md: -------------------------------------------------------------------------------- 1 | # Sujet 2 (french version) 2 | 3 | !!! tip "Astuce" 4 | **Utilisez le sélecteur de langue dans la barre de titre** pour passer d'une version localisée à l'autre de ce site de démonstration. Ce sélecteur fait partie de [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) et est **configuré automatiquement par ce plugin** ou peut être défini de manière statique depuis le [fichier mkdocs.yml](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## Ce que vous voyez en ce moment 7 | 8 | La source de cette page et son contenu média ont été localisés en suivant la 9 | [logique de localisation](#logique-de-localisation) décrite ci-dessous. Voici 10 | un rapide récapitulatif des fichiers utilisés comme source et de la structure 11 | générée que vous voyez en ce moment: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png 16 | ├── image.fr.png <-- this image file is used on the /fr version 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md <-- this file is used on the /fr version 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png <-- you see this image on the /fr version 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html <-- you are here on the /fr version 45 | ├── image.png 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Localisation automatique des médias / liens / assets 55 | 56 | ![localized image](../image.png) 57 | 58 | La source de cette image est dynamiquement localisée bien qu'elle soit 59 | référencée dans la source du markdown par `![localized image](image.png)`. 60 | Cela démontre que ce plugin vous permet de ne pas vous préoccuper du nom 61 | des fichiers dans vos liens, médias et contenus statiques : utilisez leurs 62 | noms sans extension localisée et concentrez-vous sur la traduction de vos 63 | contenus ! 64 | 65 | --- 66 | 67 | ## Logique de localisation 68 | 69 | Ce site est construit avec cette configuration : 70 | 71 | ``` 72 | plugins: 73 | - i18n: 74 | default_language: en 75 | languages: 76 | en: english 77 | fr: français 78 | ``` 79 | 80 | Ce qui veut dire que nous obtiendrons trois versions de notre site : 81 | 82 | 1. la version `default_language` qui utilisera en premier les fichiers dont 83 | l'extension est `.md` et prendra quelconque fichier en `.en.md` en repli 84 | puisque la version `en` est configurée comme la langue par défaut 85 | 2. la version localisée `/en` qui utilisera les fichiers dont l'extension est 86 | `.en.md` en premier et utilisera leur version `.md` en repli si elle existe 87 | 3. la version localisée `/fr` qui utilisera les fichiers dont l'extension est 88 | `.fr.md` en premier et utilisera en repli soit la version `.en.md` (dérivée 89 | du langage par défaut) ou `.md` 90 | 91 | En suivant cette logique, la structure `site` générée est : 92 | 93 | ``` 94 | site 95 | ├── 404.html 96 | ├── assets 97 | │   ├── images 98 | │   ├── javascripts 99 | │   └── stylesheets 100 | ├── en 101 | │   ├── image.png 102 | │   ├── index.html 103 | │   ├── topic1 104 | │   │   └── named_file 105 | │   │   └── index.html 106 | │   └── topic2 107 | │   └── index.html 108 | ├── fr 109 | │   ├── image.png 110 | │   ├── index.html 111 | │   ├── topic1 112 | │   │   └── named_file 113 | │   │   └── index.html 114 | │   └── topic2 115 | │   └── index.html 116 | ├── image.png 117 | ├── index.html 118 | ├── topic1 119 | │   └── named_file 120 | │   └── index.html 121 | └── topic2 122 | └── index.html 123 | ``` 124 | -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Topic 2 (default version only) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here on the default version 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md <-- this file is used here on the default version 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html <-- you are here on the default version 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_two_languages/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/docs_suffix_structure_two_languages/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/docs_suffix_structure_two_languages/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/hooks.py: -------------------------------------------------------------------------------- 1 | def on_nav(nav, config, files): 2 | print("on_nav hook called") 3 | return nav 4 | -------------------------------------------------------------------------------- /tests/hooks_jinja_on_env.py: -------------------------------------------------------------------------------- 1 | def value_in_frontmatter(key, metadata): 2 | """Check if a key exists in the frontmatter. 3 | 4 | Args: 5 | key (any): the key to check 6 | metadata (any): the frontmatter 7 | 8 | Returns: 9 | bool: true if exists 10 | """ 11 | if key in metadata: 12 | return metadata[key] 13 | else: 14 | return None 15 | 16 | 17 | def on_env(env, config, files, **kwargs): 18 | env.filters["value_in_frontmatter"] = value_in_frontmatter 19 | return env 20 | -------------------------------------------------------------------------------- /tests/mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: MkDocs static i18n plugin tests 2 | site_url: http://localhost 3 | -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/assets/image_non_localized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/assets/image_non_localized.png -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/english_default/index.md: -------------------------------------------------------------------------------- 1 | # English default fallback 2 | 3 | This is the english version of a page that will show up on other languages as a fallback. 4 | -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/fr/assets/image_non_localized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/fr/assets/image_non_localized.png -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/fr/english_default/index.md: -------------------------------------------------------------------------------- 1 | # English default fallback 2 | 3 | This is the english version of a page that will show up on other languages as a fallback. 4 | -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/fr/french_only/index.md: -------------------------------------------------------------------------------- 1 | # This page only exists on the French version 2 | 3 | Et voilà ! -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/fr/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/fr/image.fake -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/fr/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/fr/image.png -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/fr/topic1/named_file.md: -------------------------------------------------------------------------------- 1 | # Sujet 1 (french version) 2 | 3 | !!! tip "Astuce" 4 | **Utilisez le sélecteur de langue dans la barre de titre** pour passer d'une version localisée à l'autre de ce site de démonstration. Ce sélecteur fait partie de [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) et est **configuré automatiquement par ce plugin** ou peut être défini de manière statique depuis le [fichier mkdocs.yml](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## Ce que vous voyez en ce moment 7 | 8 | La source de cette page et son contenu média ont été localisés en suivant la 9 | [logique de localisation](#logique-de-localisation) décrite ci-dessous. Voici 10 | un rapide récapitulatif des fichiers utilisés comme source et de la structure 11 | générée que vous voyez en ce moment: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png 16 | ├── image.fr.png <-- this image file is used on the /fr version 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md <-- this file is used on the /fr version 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png <-- you see this image on the /fr version 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html <-- you are here on the /fr version 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Localisation automatique des médias / liens / assets 55 | 56 | ![localized image](../image.png) 57 | 58 | La source de cette image est dynamiquement localisée bien qu'elle soit 59 | référencée dans la source du markdown par `![localized image](image.png)`. 60 | Cela démontre que ce plugin vous permet de ne pas vous préoccuper du nom 61 | des fichiers dans vos liens, médias et contenus statiques : utilisez leurs 62 | noms sans extension localisée et concentrez-vous sur la traduction de vos 63 | contenus ! 64 | 65 | --- 66 | 67 | ## Logique de localisation 68 | 69 | Ce site est construit avec cette configuration : 70 | 71 | ``` 72 | plugins: 73 | - i18n: 74 | default_language: en 75 | languages: 76 | en: english 77 | fr: français 78 | ``` 79 | 80 | Ce qui veut dire que nous obtiendrons trois versions de notre site : 81 | 82 | 1. la version `default_language` qui utilisera en premier les fichiers dont 83 | l'extension est `.md` et prendra quelconque fichier en `.en.md` en repli 84 | puisque la version `en` est configurée comme la langue par défaut 85 | 2. la version localisée `/en` qui utilisera les fichiers dont l'extension est 86 | `.en.md` en premier et utilisera leur version `.md` en repli si elle existe 87 | 3. la version localisée `/fr` qui utilisera les fichiers dont l'extension est 88 | `.fr.md` en premier et utilisera en repli soit la version `.en.md` (dérivée 89 | du langage par défaut) ou `.md` 90 | 91 | En suivant cette logique, la structure `site` générée est : 92 | 93 | ``` 94 | site 95 | ├── 404.html 96 | ├── assets 97 | │   ├── images 98 | │   ├── javascripts 99 | │   └── stylesheets 100 | ├── en 101 | │   ├── image.png 102 | │   ├── index.html 103 | │   ├── topic1 104 | │   │   └── named_file 105 | │   │   └── index.html 106 | │   └── topic2 107 | │   └── index.html 108 | ├── fr 109 | │   ├── image.png 110 | │   ├── index.html 111 | │   ├── topic1 112 | │   │   └── named_file 113 | │   │   └── index.html 114 | │   └── topic2 115 | │   └── index.html 116 | ├── image.png 117 | ├── index.html 118 | ├── topic1 119 | │   └── named_file 120 | │   └── index.html 121 | └── topic2 122 | └── index.html 123 | ``` 124 | -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/fr/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/fr/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/fr/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Sujet 2 (french version) 2 | 3 | !!! tip "Astuce" 4 | **Utilisez le sélecteur de langue dans la barre de titre** pour passer d'une version localisée à l'autre de ce site de démonstration. Ce sélecteur fait partie de [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) et est **configuré automatiquement par ce plugin** ou peut être défini de manière statique depuis le [fichier mkdocs.yml](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## Ce que vous voyez en ce moment 7 | 8 | La source de cette page et son contenu média ont été localisés en suivant la 9 | [logique de localisation](#logique-de-localisation) décrite ci-dessous. Voici 10 | un rapide récapitulatif des fichiers utilisés comme source et de la structure 11 | générée que vous voyez en ce moment: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png 16 | ├── image.fr.png <-- this image file is used on the /fr version 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md <-- this file is used on the /fr version 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png <-- you see this image on the /fr version 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html <-- you are here on the /fr version 45 | ├── image.png 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Localisation automatique des médias / liens / assets 55 | 56 | ![localized image](../image.png) 57 | 58 | La source de cette image est dynamiquement localisée bien qu'elle soit 59 | référencée dans la source du markdown par `![localized image](image.png)`. 60 | Cela démontre que ce plugin vous permet de ne pas vous préoccuper du nom 61 | des fichiers dans vos liens, médias et contenus statiques : utilisez leurs 62 | noms sans extension localisée et concentrez-vous sur la traduction de vos 63 | contenus ! 64 | 65 | --- 66 | 67 | ## Logique de localisation 68 | 69 | Ce site est construit avec cette configuration : 70 | 71 | ``` 72 | plugins: 73 | - i18n: 74 | default_language: en 75 | languages: 76 | en: english 77 | fr: français 78 | ``` 79 | 80 | Ce qui veut dire que nous obtiendrons trois versions de notre site : 81 | 82 | 1. la version `default_language` qui utilisera en premier les fichiers dont 83 | l'extension est `.md` et prendra quelconque fichier en `.en.md` en repli 84 | puisque la version `en` est configurée comme la langue par défaut 85 | 2. la version localisée `/en` qui utilisera les fichiers dont l'extension est 86 | `.en.md` en premier et utilisera leur version `.md` en repli si elle existe 87 | 3. la version localisée `/fr` qui utilisera les fichiers dont l'extension est 88 | `.fr.md` en premier et utilisera en repli soit la version `.en.md` (dérivée 89 | du langage par défaut) ou `.md` 90 | 91 | En suivant cette logique, la structure `site` générée est : 92 | 93 | ``` 94 | site 95 | ├── 404.html 96 | ├── assets 97 | │   ├── images 98 | │   ├── javascripts 99 | │   └── stylesheets 100 | ├── en 101 | │   ├── image.png 102 | │   ├── index.html 103 | │   ├── topic1 104 | │   │   └── named_file 105 | │   │   └── index.html 106 | │   └── topic2 107 | │   └── index.html 108 | ├── fr 109 | │   ├── image.png 110 | │   ├── index.html 111 | │   ├── topic1 112 | │   │   └── named_file 113 | │   │   └── index.html 114 | │   └── topic2 115 | │   └── index.html 116 | ├── image.png 117 | ├── index.html 118 | ├── topic1 119 | │   └── named_file 120 | │   └── index.html 121 | └── topic2 122 | └── index.html 123 | ``` 124 | -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/fr/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/fr/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/fr/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/fr/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/image.fake -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/image.png -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/index.md: -------------------------------------------------------------------------------- 1 | # Home page (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md <-- this file is used here 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image here on the /en version 31 | │   ├── index.html <-- you are here on the /en version 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html <-- you are here on the default version 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | Of course, images can also not be localized just like the image below which is 64 | used by all versions of your pages: 65 | 66 | ![non localized image](assets/image_non_localized.png) 67 | 68 | --- 69 | 70 | ## Localized build logic 71 | 72 | The settings used to build this site is: 73 | 74 | ``` 75 | plugins: 76 | - i18n: 77 | default_language: en 78 | languages: 79 | en: english 80 | fr: français 81 | ``` 82 | 83 | Meaning that we will get three versions of our website: 84 | 85 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 86 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 87 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 88 | 89 | Given that logic, the following `site` structure is built: 90 | 91 | ``` 92 | site 93 | ├── 404.html 94 | ├── assets 95 | │   ├── images 96 | │   ├── javascripts 97 | │   └── stylesheets 98 | ├── en 99 | │   ├── image.png 100 | │   ├── index.html 101 | │   ├── topic1 102 | │   │   └── named_file 103 | │   │   └── index.html 104 | │   └── topic2 105 | │   └── index.html 106 | ├── fr 107 | │   ├── image.png 108 | │   ├── index.html 109 | │   ├── topic1 110 | │   │   └── named_file 111 | │   │   └── index.html 112 | │   └── topic2 113 | │   └── index.html 114 | ├── image.png 115 | ├── index.html 116 | ├── topic1 117 | │   └── named_file 118 | │   └── index.html 119 | └── topic2 120 | └── index.html 121 | ``` 122 | -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/topic1/named_file.md: -------------------------------------------------------------------------------- 1 | # Topic 1 (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used on both the default and /en versions 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md <-- this file is used on both the default and /en versions 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image on the /en version 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html <-- you are here on the /en version 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html <-- you are here on the default version 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Topic 2 (default version only) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here on the default version 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md <-- this file is used here on the default version 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html <-- you are here on the default version 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/structures/control/en_fr/docs/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_fr/docs/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/structures/control/en_fr/mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: MkDocs static i18n plugin tests 2 | site_url: http://localhost 3 | -------------------------------------------------------------------------------- /tests/structures/control/en_only/docs/assets/image_non_localized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_only/docs/assets/image_non_localized.png -------------------------------------------------------------------------------- /tests/structures/control/en_only/docs/english_default/index.md: -------------------------------------------------------------------------------- 1 | # English default fallback 2 | 3 | This is the english version of a page that will show up on other languages as a fallback. 4 | -------------------------------------------------------------------------------- /tests/structures/control/en_only/docs/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_only/docs/image.fake -------------------------------------------------------------------------------- /tests/structures/control/en_only/docs/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_only/docs/image.png -------------------------------------------------------------------------------- /tests/structures/control/en_only/docs/index.md: -------------------------------------------------------------------------------- 1 | # Home page (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md <-- this file is used here 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image here on the /en version 31 | │   ├── index.html <-- you are here on the /en version 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html <-- you are here on the default version 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | Of course, images can also not be localized just like the image below which is 64 | used by all versions of your pages: 65 | 66 | ![non localized image](assets/image_non_localized.png) 67 | 68 | --- 69 | 70 | ## Localized build logic 71 | 72 | The settings used to build this site is: 73 | 74 | ``` 75 | plugins: 76 | - i18n: 77 | default_language: en 78 | languages: 79 | en: english 80 | fr: français 81 | ``` 82 | 83 | Meaning that we will get three versions of our website: 84 | 85 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 86 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 87 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 88 | 89 | Given that logic, the following `site` structure is built: 90 | 91 | ``` 92 | site 93 | ├── 404.html 94 | ├── assets 95 | │   ├── images 96 | │   ├── javascripts 97 | │   └── stylesheets 98 | ├── en 99 | │   ├── image.png 100 | │   ├── index.html 101 | │   ├── topic1 102 | │   │   └── named_file 103 | │   │   └── index.html 104 | │   └── topic2 105 | │   └── index.html 106 | ├── fr 107 | │   ├── image.png 108 | │   ├── index.html 109 | │   ├── topic1 110 | │   │   └── named_file 111 | │   │   └── index.html 112 | │   └── topic2 113 | │   └── index.html 114 | ├── image.png 115 | ├── index.html 116 | ├── topic1 117 | │   └── named_file 118 | │   └── index.html 119 | └── topic2 120 | └── index.html 121 | ``` 122 | -------------------------------------------------------------------------------- /tests/structures/control/en_only/docs/topic1/named_file.md: -------------------------------------------------------------------------------- 1 | # Topic 1 (default version + english version) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used on both the default and /en versions 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md <-- this file is used on both the default and /en versions 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png <-- you see this image on the /en version 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html <-- you are here on the /en version 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html <-- you are here on the default version 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/structures/control/en_only/docs/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_only/docs/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/structures/control/en_only/docs/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Topic 2 (default version only) 2 | 3 | !!! tip 4 | **Use the language switcher in the header** to switch between the localized versions of this demo website. This switcher is part of [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) and is **automatically configured by this plugin** or can be statically configured from the [mkdocs.yml file](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## What you are seeing now 7 | 8 | This page source file and media content have been localized after applying 9 | the [localized build logic](#localized-build-logic) described below. Here is a 10 | quick recap of the files used as source and the generated build structure of 11 | what you see: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png <-- this image file is used here on the default version 16 | ├── image.fr.png 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md <-- this file is used here on the default version 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png <-- you see this image here on the default version 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html <-- you are here on the default version 52 | ``` 53 | 54 | ## Automatic media / link / asset localization 55 | 56 | ![localized image](../image.png) 57 | 58 | This image source is dynamically localized while still being referenced in the 59 | markdown source of the page as `![localized image](../image.png)`. This means that 60 | this plugin allows you to not worry about links, media and static content file 61 | names, just use their simple name and concentrate on your content translation! 62 | 63 | --- 64 | 65 | ## Localized build logic 66 | 67 | The settings used to build this site is: 68 | 69 | ``` 70 | plugins: 71 | - i18n: 72 | default_language: en 73 | languages: 74 | en: english 75 | fr: français 76 | ``` 77 | 78 | Meaning that we will get three versions of our website: 79 | 80 | 1. the `default_language` version which will use any `.md` documentation file first and fallback to any `.en.md` file found since `en` is the default language 81 | 2. the `/en` language version which will use any `.en.md` documentation file first and fallback to any `.md` file found 82 | 3. the `/fr` language version which will use any `.fr.md` documentation file first and fallback to either `.en.md` file (default language) or `.md` file (default language fallback) whichever comes first 83 | 84 | Given that logic, the following `site` structure is built: 85 | 86 | ``` 87 | site 88 | ├── 404.html 89 | ├── assets 90 | │   ├── images 91 | │   ├── javascripts 92 | │   └── stylesheets 93 | ├── en 94 | │   ├── image.png 95 | │   ├── index.html 96 | │   ├── topic1 97 | │   │   └── named_file 98 | │   │   └── index.html 99 | │   └── topic2 100 | │   └── index.html 101 | ├── fr 102 | │   ├── image.png 103 | │   ├── index.html 104 | │   ├── topic1 105 | │   │   └── named_file 106 | │   │   └── index.html 107 | │   └── topic2 108 | │   └── index.html 109 | ├── image.png 110 | ├── index.html 111 | ├── topic1 112 | │   └── named_file 113 | │   └── index.html 114 | └── topic2 115 | └── index.html 116 | ``` 117 | -------------------------------------------------------------------------------- /tests/structures/control/en_only/docs/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_only/docs/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/structures/control/en_only/docs/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/en_only/docs/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/structures/control/en_only/mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: MkDocs static i18n plugin tests 2 | site_url: http://localhost 3 | -------------------------------------------------------------------------------- /tests/structures/control/fr_only/docs/assets/image_non_localized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_only/docs/assets/image_non_localized.png -------------------------------------------------------------------------------- /tests/structures/control/fr_only/docs/french_only/index.md: -------------------------------------------------------------------------------- 1 | # This page only exists on the French version 2 | 3 | Et voilà ! -------------------------------------------------------------------------------- /tests/structures/control/fr_only/docs/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_only/docs/image.fake -------------------------------------------------------------------------------- /tests/structures/control/fr_only/docs/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_only/docs/image.png -------------------------------------------------------------------------------- /tests/structures/control/fr_only/docs/topic1/named_file.md: -------------------------------------------------------------------------------- 1 | # Sujet 1 (french version) 2 | 3 | !!! tip "Astuce" 4 | **Utilisez le sélecteur de langue dans la barre de titre** pour passer d'une version localisée à l'autre de ce site de démonstration. Ce sélecteur fait partie de [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) et est **configuré automatiquement par ce plugin** ou peut être défini de manière statique depuis le [fichier mkdocs.yml](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## Ce que vous voyez en ce moment 7 | 8 | La source de cette page et son contenu média ont été localisés en suivant la 9 | [logique de localisation](#logique-de-localisation) décrite ci-dessous. Voici 10 | un rapide récapitulatif des fichiers utilisés comme source et de la structure 11 | générée que vous voyez en ce moment: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png 16 | ├── image.fr.png <-- this image file is used on the /fr version 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md <-- this file is used on the /fr version 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png <-- you see this image on the /fr version 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html <-- you are here on the /fr version 43 | │   └── topic2 44 | │   └── index.html 45 | ├── image.png 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Localisation automatique des médias / liens / assets 55 | 56 | ![localized image](../image.png) 57 | 58 | La source de cette image est dynamiquement localisée bien qu'elle soit 59 | référencée dans la source du markdown par `![localized image](image.png)`. 60 | Cela démontre que ce plugin vous permet de ne pas vous préoccuper du nom 61 | des fichiers dans vos liens, médias et contenus statiques : utilisez leurs 62 | noms sans extension localisée et concentrez-vous sur la traduction de vos 63 | contenus ! 64 | 65 | --- 66 | 67 | ## Logique de localisation 68 | 69 | Ce site est construit avec cette configuration : 70 | 71 | ``` 72 | plugins: 73 | - i18n: 74 | default_language: en 75 | languages: 76 | en: english 77 | fr: français 78 | ``` 79 | 80 | Ce qui veut dire que nous obtiendrons trois versions de notre site : 81 | 82 | 1. la version `default_language` qui utilisera en premier les fichiers dont 83 | l'extension est `.md` et prendra quelconque fichier en `.en.md` en repli 84 | puisque la version `en` est configurée comme la langue par défaut 85 | 2. la version localisée `/en` qui utilisera les fichiers dont l'extension est 86 | `.en.md` en premier et utilisera leur version `.md` en repli si elle existe 87 | 3. la version localisée `/fr` qui utilisera les fichiers dont l'extension est 88 | `.fr.md` en premier et utilisera en repli soit la version `.en.md` (dérivée 89 | du langage par défaut) ou `.md` 90 | 91 | En suivant cette logique, la structure `site` générée est : 92 | 93 | ``` 94 | site 95 | ├── 404.html 96 | ├── assets 97 | │   ├── images 98 | │   ├── javascripts 99 | │   └── stylesheets 100 | ├── en 101 | │   ├── image.png 102 | │   ├── index.html 103 | │   ├── topic1 104 | │   │   └── named_file 105 | │   │   └── index.html 106 | │   └── topic2 107 | │   └── index.html 108 | ├── fr 109 | │   ├── image.png 110 | │   ├── index.html 111 | │   ├── topic1 112 | │   │   └── named_file 113 | │   │   └── index.html 114 | │   └── topic2 115 | │   └── index.html 116 | ├── image.png 117 | ├── index.html 118 | ├── topic1 119 | │   └── named_file 120 | │   └── index.html 121 | └── topic2 122 | └── index.html 123 | ``` 124 | -------------------------------------------------------------------------------- /tests/structures/control/fr_only/docs/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_only/docs/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/structures/control/fr_only/docs/topic2/README.md: -------------------------------------------------------------------------------- 1 | # Sujet 2 (french version) 2 | 3 | !!! tip "Astuce" 4 | **Utilisez le sélecteur de langue dans la barre de titre** pour passer d'une version localisée à l'autre de ce site de démonstration. Ce sélecteur fait partie de [mkdocs-material >= 7.1.0](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector) et est **configuré automatiquement par ce plugin** ou peut être défini de manière statique depuis le [fichier mkdocs.yml](https://github.com/ultrabug/mkdocs-static-i18n/blob/main/mkdocs.yml). 5 | 6 | ## Ce que vous voyez en ce moment 7 | 8 | La source de cette page et son contenu média ont été localisés en suivant la 9 | [logique de localisation](#logique-de-localisation) décrite ci-dessous. Voici 10 | un rapide récapitulatif des fichiers utilisés comme source et de la structure 11 | générée que vous voyez en ce moment: 12 | 13 | ``` 14 | docs 15 | ├── image.en.png 16 | ├── image.fr.png <-- this image file is used on the /fr version 17 | ├── index.fr.md 18 | ├── index.md 19 | ├── topic1 20 | │   ├── named_file.en.md 21 | │   └── named_file.fr.md <-- this file is used on the /fr version 22 | └── topic2 23 | ├── index.en.md 24 | └── index.md 25 | ``` 26 | 27 | ``` 28 | site 29 | ├── en 30 | │   ├── image.png 31 | │   ├── index.html 32 | │   ├── topic1 33 | │   │   └── named_file 34 | │   │   └── index.html 35 | │   └── topic2 36 | │   └── index.html 37 | ├── fr 38 | │   ├── image.png <-- you see this image on the /fr version 39 | │   ├── index.html 40 | │   ├── topic1 41 | │   │   └── named_file 42 | │   │   └── index.html 43 | │   └── topic2 44 | │   └── index.html <-- you are here on the /fr version 45 | ├── image.png 46 | ├── index.html 47 | ├── topic1 48 | │   └── named_file 49 | │   └── index.html 50 | └── topic2 51 | └── index.html 52 | ``` 53 | 54 | ## Localisation automatique des médias / liens / assets 55 | 56 | ![localized image](../image.png) 57 | 58 | La source de cette image est dynamiquement localisée bien qu'elle soit 59 | référencée dans la source du markdown par `![localized image](image.png)`. 60 | Cela démontre que ce plugin vous permet de ne pas vous préoccuper du nom 61 | des fichiers dans vos liens, médias et contenus statiques : utilisez leurs 62 | noms sans extension localisée et concentrez-vous sur la traduction de vos 63 | contenus ! 64 | 65 | --- 66 | 67 | ## Logique de localisation 68 | 69 | Ce site est construit avec cette configuration : 70 | 71 | ``` 72 | plugins: 73 | - i18n: 74 | default_language: en 75 | languages: 76 | en: english 77 | fr: français 78 | ``` 79 | 80 | Ce qui veut dire que nous obtiendrons trois versions de notre site : 81 | 82 | 1. la version `default_language` qui utilisera en premier les fichiers dont 83 | l'extension est `.md` et prendra quelconque fichier en `.en.md` en repli 84 | puisque la version `en` est configurée comme la langue par défaut 85 | 2. la version localisée `/en` qui utilisera les fichiers dont l'extension est 86 | `.en.md` en premier et utilisera leur version `.md` en repli si elle existe 87 | 3. la version localisée `/fr` qui utilisera les fichiers dont l'extension est 88 | `.fr.md` en premier et utilisera en repli soit la version `.en.md` (dérivée 89 | du langage par défaut) ou `.md` 90 | 91 | En suivant cette logique, la structure `site` générée est : 92 | 93 | ``` 94 | site 95 | ├── 404.html 96 | ├── assets 97 | │   ├── images 98 | │   ├── javascripts 99 | │   └── stylesheets 100 | ├── en 101 | │   ├── image.png 102 | │   ├── index.html 103 | │   ├── topic1 104 | │   │   └── named_file 105 | │   │   └── index.html 106 | │   └── topic2 107 | │   └── index.html 108 | ├── fr 109 | │   ├── image.png 110 | │   ├── index.html 111 | │   ├── topic1 112 | │   │   └── named_file 113 | │   │   └── index.html 114 | │   └── topic2 115 | │   └── index.html 116 | ├── image.png 117 | ├── index.html 118 | ├── topic1 119 | │   └── named_file 120 | │   └── index.html 121 | └── topic2 122 | └── index.html 123 | ``` 124 | -------------------------------------------------------------------------------- /tests/structures/control/fr_only/docs/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_only/docs/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/structures/control/fr_only/docs/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_only/docs/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/structures/control/fr_only/mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: MkDocs static i18n plugin tests 2 | site_url: http://localhost 3 | -------------------------------------------------------------------------------- /tests/structures/control/fr_with_default/docs/assets/image_non_localized.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_with_default/docs/assets/image_non_localized.png -------------------------------------------------------------------------------- /tests/structures/control/fr_with_default/docs/english_default/index.md: -------------------------------------------------------------------------------- 1 | # English default fallback 2 | 3 | This is the english version of a page that will show up on other languages as a fallback. 4 | -------------------------------------------------------------------------------- /tests/structures/control/fr_with_default/docs/french_only/index.md: -------------------------------------------------------------------------------- 1 | # This page only exists on the French version 2 | 3 | Et voilà ! -------------------------------------------------------------------------------- /tests/structures/control/fr_with_default/docs/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_with_default/docs/image.fake -------------------------------------------------------------------------------- /tests/structures/control/fr_with_default/docs/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_with_default/docs/image.png -------------------------------------------------------------------------------- /tests/structures/control/fr_with_default/docs/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_with_default/docs/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/structures/control/fr_with_default/docs/topic2/release_notes_17.1.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_with_default/docs/topic2/release_notes_17.1.md -------------------------------------------------------------------------------- /tests/structures/control/fr_with_default/docs/topic2/release_notes_17.2.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_with_default/docs/topic2/release_notes_17.2.md -------------------------------------------------------------------------------- /tests/structures/control/fr_with_default/mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: MkDocs static i18n plugin tests 2 | site_url: http://localhost/fr/ 3 | -------------------------------------------------------------------------------- /tests/structures/control/fr_without_default/docs/french_only/index.md: -------------------------------------------------------------------------------- 1 | # This page only exists on the French version 2 | 3 | Et voilà ! -------------------------------------------------------------------------------- /tests/structures/control/fr_without_default/docs/image.fake: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_without_default/docs/image.fake -------------------------------------------------------------------------------- /tests/structures/control/fr_without_default/docs/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_without_default/docs/image.png -------------------------------------------------------------------------------- /tests/structures/control/fr_without_default/docs/topic2/1.1.filename.html: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ultrabug/mkdocs-static-i18n/5eda9fa5556d4055e06c96727593ec8c42dbc4a8/tests/structures/control/fr_without_default/docs/topic2/1.1.filename.html -------------------------------------------------------------------------------- /tests/structures/control/fr_without_default/mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: MkDocs static i18n plugin tests 2 | site_url: http://localhost/fr/ 3 | -------------------------------------------------------------------------------- /tests/test_admonitions.py: -------------------------------------------------------------------------------- 1 | import re 2 | import logging 3 | from pathlib import Path 4 | 5 | from mkdocs.commands.build import build 6 | from mkdocs.config.base import load_config 7 | 8 | ADMONITIONS_CONFIG_WARNING = "mkdocs_static_i18n: admonition_translations used, but admonitions won't be rendered properly without 'admonition' in mkdocs.yml's markdown_extensions." 9 | 10 | class LogHandlerList(logging.Handler): 11 | def __init__(self): 12 | super().__init__() 13 | self.messages = [] 14 | 15 | def handle(self, record): 16 | rv = self.filter(record) 17 | if rv: 18 | # Use levelno for keys so they can be sorted later 19 | self.messages.append(record.getMessage()) 20 | return rv 21 | 22 | def test_invalid_config(): 23 | mkdocs_config = load_config( 24 | "tests/mkdocs.yml", 25 | theme={"name": "material"}, 26 | docs_dir="admonitions/", 27 | plugins={ 28 | "i18n": { 29 | "languages": [ 30 | { 31 | "locale": "en", 32 | "name": "english", 33 | "default": True, 34 | }, 35 | { 36 | "locale": "fr", 37 | "name": "français", 38 | "build": True, 39 | "admonition_translations": { 40 | "tip": "Conseil", 41 | "warning": "Avertissement", 42 | } 43 | }, 44 | ], 45 | }, 46 | }, 47 | ) 48 | 49 | warning_list = LogHandlerList() 50 | warning_list.setLevel(logging.WARNING) 51 | logging.getLogger('mkdocs').addHandler(warning_list) 52 | 53 | build(mkdocs_config) 54 | 55 | assert(ADMONITIONS_CONFIG_WARNING in warning_list.messages) 56 | 57 | 58 | def test_plugin_no_use_directory_urls_default_language_only(): 59 | mkdocs_config = load_config( 60 | "tests/mkdocs.yml", 61 | theme={"name": "material"}, 62 | docs_dir="admonitions/", 63 | plugins={ 64 | "i18n": { 65 | "languages": [ 66 | { 67 | "locale": "en", 68 | "name": "english", 69 | "default": True, 70 | }, 71 | { 72 | "locale": "fr", 73 | "name": "français", 74 | "build": True, 75 | "admonition_translations": { 76 | "tip": "Conseil", 77 | "warning": "Avertissement", 78 | } 79 | }, 80 | ], 81 | }, 82 | }, 83 | markdown_extensions=["admonition"], 84 | ) 85 | 86 | warning_list = LogHandlerList() 87 | warning_list.setLevel(logging.WARNING) 88 | logging.getLogger('mkdocs').addHandler(warning_list) 89 | 90 | build(mkdocs_config) 91 | 92 | # assert(all(item == ADMONITIONS_CONFIG_WARNING) for item in warning_list.messages) 93 | assert(ADMONITIONS_CONFIG_WARNING not in warning_list.messages) 94 | 95 | site_dir = mkdocs_config["site_dir"] 96 | 97 | with open(site_dir+'/index.html') as f: 98 | admonition_titles = re.findall(r"

([^<]*)", f.read()) 99 | assert(admonition_titles == ['Tip', 'Tip', 'Warning', 'Heey']) 100 | 101 | with open(site_dir+'/fr/index.html') as f: 102 | admonition_titles = re.findall(r"

([^<]*)", f.read()) 103 | assert(admonition_titles == ['Conseil', 'Conseil', 'Avertissement', 'Heey']) 104 | -------------------------------------------------------------------------------- /tests/test_config.py: -------------------------------------------------------------------------------- 1 | from mkdocs.config.base import load_config 2 | 3 | from mkdocs_static_i18n.plugin import I18n 4 | 5 | 6 | def test_plugin_single_language_en(): 7 | plugin = I18n() 8 | plugin.load_config({"languages": [{"locale": "en", "name": "english", "default": True}]}) 9 | config = load_config( 10 | "tests/mkdocs.yml", 11 | theme={"name": "mkdocs"}, 12 | use_directory_urls=True, 13 | docs_dir="docs_suffix_structure_one_language/", 14 | ) 15 | result = plugin.on_config(config) 16 | assert str(result["theme"]["locale"]) == "en" 17 | 18 | 19 | def test_plugin_single_language_fr(): 20 | plugin = I18n() 21 | plugin.load_config({"languages": [{"locale": "fr", "name": "français", "default": True}]}) 22 | config = load_config( 23 | "tests/mkdocs.yml", 24 | theme={"name": "mkdocs"}, 25 | use_directory_urls=True, 26 | docs_dir="docs_suffix_structure_one_language/", 27 | ) 28 | result = plugin.on_config(config) 29 | assert str(result["theme"]["locale"]) == "fr" 30 | 31 | 32 | def test_plugin_theme_sitemap(): 33 | plugin = I18n() 34 | plugin.load_config({"languages": [{"locale": "fr", "name": "français", "default": True}]}) 35 | config = load_config( 36 | "tests/mkdocs.yml", 37 | theme={"name": "mkdocs"}, 38 | use_directory_urls=True, 39 | docs_dir="docs_suffix_structure_one_language/", 40 | ) 41 | result = plugin.on_config(config) 42 | assert result["theme"].dirs[0].endswith("custom_i18n_sitemap") 43 | -------------------------------------------------------------------------------- /tests/test_details.py: -------------------------------------------------------------------------------- 1 | import re 2 | import logging 3 | from pathlib import Path 4 | 5 | from mkdocs.commands.build import build 6 | from mkdocs.config.base import load_config 7 | 8 | def test_plugin_no_use_directory_urls_default_language_only(): 9 | mkdocs_config = load_config( 10 | "tests/mkdocs.yml", 11 | theme={"name": "material"}, 12 | docs_dir="details/", 13 | plugins={ 14 | "i18n": { 15 | "languages": [ 16 | { 17 | "locale": "en", 18 | "name": "english", 19 | "default": True, 20 | }, 21 | { 22 | "locale": "fr", 23 | "name": "français", 24 | "build": True, 25 | "admonition_translations": { 26 | "tip": "Conseil", 27 | "warning": "Avertissement", 28 | } 29 | }, 30 | ], 31 | }, 32 | }, 33 | markdown_extensions=["admonition", "pymdownx.details"], 34 | ) 35 | 36 | build(mkdocs_config) 37 | 38 | site_dir = mkdocs_config["site_dir"] 39 | 40 | with open(site_dir+'/index.html') as f: 41 | admonition_titles = re.findall(r"

([^<]*)", f.read()) 42 | assert(admonition_titles == ['Tip', 'Tip', 'Tip', 'Tip', 'Warning', 'Heey']) 43 | 44 | with open(site_dir+'/fr/index.html') as f: 45 | admonition_titles = re.findall(r"([^<]*)", f.read()) 46 | assert(admonition_titles == ['Conseil', 'Conseil', 'Conseil', 'Conseil', 'Avertissement', 'Heey']) 47 | -------------------------------------------------------------------------------- /tests/test_hooks.py: -------------------------------------------------------------------------------- 1 | from mkdocs.commands.build import build 2 | from mkdocs.config.base import load_config 3 | 4 | 5 | def test_hooks_working(): 6 | mkdocs_config = load_config( 7 | "tests/mkdocs.yml", 8 | theme={"name": "mkdocs"}, 9 | use_directory_urls=True, 10 | docs_dir="docs_suffix_structure_two_languages/", 11 | plugins={ 12 | "i18n": { 13 | "languages": [ 14 | {"locale": "en", "name": "english", "default": True}, 15 | {"locale": "fr", "name": "français"}, 16 | ], 17 | }, 18 | }, 19 | hooks=["hooks.py"], 20 | ) 21 | build(mkdocs_config) 22 | 23 | 24 | def test_hooks_env_modified(): 25 | mkdocs_config = load_config( 26 | "tests/mkdocs.yml", 27 | theme={"name": "mkdocs", "custom_dir": "theme_overrides"}, 28 | use_directory_urls=True, 29 | docs_dir="docs_suffix_structure_two_languages/", 30 | plugins={ 31 | "i18n": { 32 | "languages": [ 33 | {"locale": "en", "name": "english", "default": True}, 34 | {"locale": "fr", "name": "français"}, 35 | ], 36 | }, 37 | }, 38 | hooks=["hooks_jinja_on_env.py"], 39 | site_dir="/tmp/xoxo/", 40 | ) 41 | build(mkdocs_config) 42 | -------------------------------------------------------------------------------- /tests/test_locale_type.py: -------------------------------------------------------------------------------- 1 | import pytest 2 | from mkdocs.config.base import ValidationError 3 | 4 | from mkdocs_static_i18n.config import Locale 5 | 6 | 7 | def test_locale_valid_values(): 8 | locale = Locale(str) 9 | valid_locales = [ 10 | "en", 11 | "en-US", 12 | "en_US", 13 | "en-GB", 14 | "en-UK", # valid pattern, but the territory code is not a valid ISO-3166-1 alpha-2 code 15 | "fr", 16 | "fr-FR", 17 | "fr_FR", 18 | "ga-IE", 19 | "sr-Latn", 20 | "th", 21 | "zh-Hans", 22 | "zh-Hans-CN", 23 | "zh-Hans-SG", 24 | "zh-Hant", 25 | "zh-Hant-HK", 26 | "zh-Hant-TW", 27 | ] 28 | for value in valid_locales: 29 | assert locale.run_validation(value) == value 30 | 31 | 32 | def test_locale_invalid_values(): 33 | locale = Locale(str) 34 | invalid_locales = [ 35 | "123", # language code must be two-letter ISO-639-1 36 | "english", # language code must be two-letter ISO-639-1 37 | "EN", # language code must be lower case 38 | "en-us", # territory code must be upper case 39 | "en-US-", # there must be no trailing dash 40 | "en_", # there must be no trailing underscore 41 | "zh-Hans-sg", # territory code must be upper case 42 | ] 43 | for value in invalid_locales: 44 | with pytest.raises(ValidationError): 45 | locale.run_validation(value) 46 | 47 | 48 | def test_locale_null_value(): 49 | locale = Locale(str) 50 | assert locale.run_validation("null") == "null" 51 | -------------------------------------------------------------------------------- /tests/test_rtd.py: -------------------------------------------------------------------------------- 1 | from pathlib import Path 2 | 3 | from mkdocs.commands.build import build 4 | from mkdocs.config.base import load_config 5 | 6 | 7 | def test_rtd_fontfiles(): 8 | config_base_rtd = load_config( 9 | "tests/mkdocs.yml", 10 | theme={"name": "readthedocs"}, 11 | use_directory_urls=True, 12 | docs_dir="docs_suffix_structure_two_languages/", 13 | ) 14 | 15 | config_plugin_rtd = load_config( 16 | "tests/mkdocs.yml", 17 | theme={"name": "readthedocs"}, 18 | use_directory_urls=True, 19 | docs_dir="docs_suffix_structure_two_languages/", 20 | plugins={ 21 | "i18n": { 22 | "languages": [ 23 | { 24 | "locale": "en", 25 | "name": "english", 26 | "default": True, 27 | }, 28 | {"locale": "fr", "name": "français"}, 29 | ], 30 | }, 31 | }, 32 | ) 33 | 34 | base_site_dir = config_base_rtd["site_dir"] 35 | i18n_site_dir = config_plugin_rtd["site_dir"] 36 | 37 | build(config_base_rtd) 38 | build(config_plugin_rtd) 39 | 40 | base_font_files = [ 41 | str(p).replace(base_site_dir, "") for p in Path(base_site_dir, "fonts").glob("**/*") 42 | ] 43 | i18n_font_files = [ 44 | str(p).replace(i18n_site_dir, "") for p in Path(i18n_site_dir, "fonts").glob("**/*") 45 | ] 46 | assert sorted(base_font_files) == sorted(i18n_font_files) 47 | -------------------------------------------------------------------------------- /tests/theme_overrides/content.html: -------------------------------------------------------------------------------- 1 | Testing on_env hooks 2 | 3 | {% set test = "comments" | value_in_frontmatter(page.meta) %} 4 | --------------------------------------------------------------------------------