Package: pelican-i18n-subsites
This plugin extends the translations functionality by creating
internationalized sub-sites for the default site.This plugin is designed for Pelican 3.4 and later.What it doesWhen the content of the main site is being generated, the settings
are saved and the generation stops when content is ready to be
written. While reading source files and generating content objects,
the output queue is modified in certain ways:translations that will appear as native in a different (sub-)site
will be removeduntranslated articles will be transformed to drafts ifI18N_UNTRANSLATED_ARTICLESis'hide'(default), removed if'remove'or kept as they are if'keep'.untranslated pages will be transformed into hidden pages ifI18N_UNTRANSLATED_PAGESis'hide'(default), removed if'remove'or kept as they are if'keep'.’’additional content manipulation similar to articles and pages can
be specified for custom generators in theI18N_GENERATOR_INFOsetting.For each language specified in theI18N_SUBSITESdictionary the
settings overrides are applied to the settings from the main site
and a new sub-site is generated in the same way as with the main
site until content is ready to be written.When all (sub-)sites are waiting for content writing, all removed
contents, translations and static files are interlinked across the
(sub-)sites.Finally, all the output is written.InstallationThis plugin can be installed via:python-mpipinstallpelican-i18n-subsitesSetting it upFor each extra used language code, a language-specific settings overrides
dictionary must be given (but can be empty) in theI18N_SUBSITESdictionaryPLUGINS=['i18n_subsites',...]# mapping: language_code -> settings_overrides_dictI18N_SUBSITES={'cz':{'SITENAME':'Hezkej blog',}}You must also have the following in your pelican configurationJINJA_ENVIRONMENT={'extensions':['jinja2.ext.i18n'],}Default and special overridesThe settings overrides may contain arbitrary settings, however, there
are some that are handled in a special way:SITEURLAny overrides to this setting should ensure that there is some level
of hierarchy between all (sub-)sites, because Pelican makes all URLs
relative toSITEURLand the plugin can only cross-link between
the sites using this hierarchy. For instance, with the main sitehttp://example.coma sub-sitehttp://example.com/dewill
work, buthttp://de.example.comwill not. If not overridden, the
language code (the language identifier used in thelangmetadata) is appended to the mainSITEURLfor each sub-site.OUTPUT_PATH,CACHE_PATHIf not overridden, the language code is appended as withSITEURL.
Separate cache paths are required as parser results depend on the locale.STATIC_PATHS,THEME_STATIC_PATHSIf not overridden, they are set to[]and all links to static
files are cross-linked to the main site.THEME,THEME_STATIC_DIRIf overridden, the logic withTHEME_STATIC_PATHSdoes not apply.DEFAULT_LANGThis should not be overridden as the plugin changes it to the
language code of each sub-site to change what is perceived as translations.Localizing templatesMost importantly, this plugin can use localized templates for each
sub-site. There are two approaches to having the templates localized:You can set a differentTHEMEoverride for each language inI18N_SUBSITES, e.g. by making a copy of a thememy_themetomy_theme_langand then editing the templates in the new
localized theme. This approach means you don’t have to deal with
gettext*.pofiles, but it is harder to maintain over time.You use only one theme and localize the templates using thejinja2.ext.i18n Jinja2 extension. For a kickstart
read thisguide.Additional context variablesIt may be convenient to add language buttons to your theme in addition
to the translation links of articles and pages. These buttons could,
for example, point to theSITEURLof each (sub-)site. For this
reason the plugin adds these variables to the template context:main_langThe language of the main site — the originalDEFAULT_LANGmain_siteurlTheSITEURLof the main site — the originalSITEURLlang_siteurlsAn ordered dictionary, mapping all used languages to theirSITEURL. Themain_langis the first key withmain_siteurlas the value. This dictionary is useful for implementing global
language buttons that show the language of the currently viewed
(sub-)site too.extra_siteurlsAn ordered dictionary, subset oflang_siteurls, the currentDEFAULT_LANGof the rendered (sub-)site is not included, so for
each (sub-)siteset(extra_siteurls) == set(lang_siteurls) -set([DEFAULT_LANG]). This dictionary is useful for implementing
global language buttons that do not show the current language.relpath_to_siteA function that returns a relative path from the first (sub-)site to
the second (sub-)site where the (sub-)sites are identified by the
language codes given as two arguments.If you don’t like the default ordering of the ordered dictionaries,
use a Jinja2 filter to alter the ordering.All the siteurls above are always absolute even in the case ofRELATIVE_URLS == True(it would be to complicated to replicate the
Pelican internals for local siteurls), so you may rather use something
like{{ SITEURL}}/{{relpath_to_site(DEFAULT_LANG, main_lang }}to link to the main site.This shorthowtoshows two
example implementations of language buttons.Additional config optionIf you use plugins likephotos,thumbnailerand want to prevent
the system from copying the files into each language directory, it is possible
to set a list of directories in the variableI18N_LINK_DIRS.
For each path a symbolic link is created which links to the original directory.I18N_LINK_DIRS=['images/thumbnails','photos']└── output/                                              # base output directory
    ├── images/
    │   └── thumbnails/                                  # original directory
    ├── photos/                                          # original directory
    └─── de/                                             # language subfolder
         ├── photos -> /output/photos                    # symbolic link to original directory
         └── images/
             └── thumbnails -> /output/images/thumbnails # symbolic link to original directoryUsage notesIt ismandatoryto specifylangmetadata for each article
and page asDEFAULT_LANGis later changed for each sub-site, so
content withoutlangmetadata would be rendered in every
(sub-)site.As with the original translations functionality,slugmetadata
is used to group translations. It is therefore often convenient to
compensate for this by overriding the content URL (which defaults to
slug) using theurlandsave_asmetadata. You could also
give articles e.g.namemetadata and use it inARTICLE_URL ='{name}.html'.DevelopmentA demo and a test site is in thegh-pagesbranch and can be seen
athttp://smartass101.github.io/pelican-plugins/A demo site used for automated end to end testing is defined in
i18n_subsites/test_data.Run the tests usingpython-munittest i18n_subsites/test_i18n_subsites.pyContributingContributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting onexisting issues.To start contributing to this plugin, review theContributing to Pelicandocumentation, beginning with theContributing Codesection.LicenseThis project is licensed under the AGPL-3.0 license.