README.rst 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166
  1. =======================
  2. I18N Sub-sites Plugin
  3. =======================
  4. This plugin extends the translations functionality by creating
  5. internationalized sub-sites for the default site.
  6. This plugin is designed for Pelican 3.4 and later.
  7. What it does
  8. ============
  9. 1. When the content of the main site is being generated, the settings
  10. are saved and the generation stops when content is ready to be
  11. written. While reading source files and generating content objects,
  12. the output queue is modified in certain ways:
  13. - translations that will appear as native in a different (sub-)site
  14. will be removed
  15. - untranslated articles will be transformed to drafts if
  16. ``I18N_UNTRANSLATED_ARTICLES`` is ``'hide'`` (default), removed if
  17. ``'remove'`` or kept as they are if ``'keep'``.
  18. - untranslated pages will be transformed into hidden pages if
  19. ``I18N_UNTRANSLATED_PAGES`` is ``'hide'`` (default), removed if
  20. ``'remove'`` or kept as they are if ``'keep'``.''
  21. - additional content manipulation similar to articles and pages can
  22. be specified for custom generators in the ``I18N_GENERATOR_INFO``
  23. setting.
  24. 2. For each language specified in the ``I18N_SUBSITES`` dictionary the
  25. settings overrides are applied to the settings from the main site
  26. and a new sub-site is generated in the same way as with the main
  27. site until content is ready to be written.
  28. 3. When all (sub-)sites are waiting for content writing, all removed
  29. contents, translations and static files are interlinked across the
  30. (sub-)sites.
  31. 4. Finally, all the output is written.
  32. Setting it up
  33. =============
  34. For each extra used language code, a language-specific settings overrides
  35. dictionary must be given (but can be empty) in the ``I18N_SUBSITES`` dictionary
  36. .. code-block:: python
  37. PLUGINS = ['i18n_subsites', ...]
  38. # mapping: language_code -> settings_overrides_dict
  39. I18N_SUBSITES = {
  40. 'cz': {
  41. 'SITENAME': 'Hezkej blog',
  42. }
  43. }
  44. You must also have the following in your pelican configuration
  45. .. code-block:: python
  46. JINJA_ENVIRONMENT = {
  47. 'extensions': ['jinja2.ext.i18n'],
  48. }
  49. Default and special overrides
  50. -----------------------------
  51. The settings overrides may contain arbitrary settings, however, there
  52. are some that are handled in a special way:
  53. ``SITEURL``
  54. Any overrides to this setting should ensure that there is some level
  55. of hierarchy between all (sub-)sites, because Pelican makes all URLs
  56. relative to ``SITEURL`` and the plugin can only cross-link between
  57. the sites using this hierarchy. For instance, with the main site
  58. ``http://example.com`` a sub-site ``http://example.com/de`` will
  59. work, but ``http://de.example.com`` will not. If not overridden, the
  60. language code (the language identifier used in the ``lang``
  61. metadata) is appended to the main ``SITEURL`` for each sub-site.
  62. ``OUTPUT_PATH``, ``CACHE_PATH``
  63. If not overridden, the language code is appended as with ``SITEURL``.
  64. Separate cache paths are required as parser results depend on the locale.
  65. ``STATIC_PATHS``, ``THEME_STATIC_PATHS``
  66. If not overridden, they are set to ``[]`` and all links to static
  67. files are cross-linked to the main site.
  68. ``THEME``, ``THEME_STATIC_DIR``
  69. If overridden, the logic with ``THEME_STATIC_PATHS`` does not apply.
  70. ``DEFAULT_LANG``
  71. This should not be overridden as the plugin changes it to the
  72. language code of each sub-site to change what is perceived as translations.
  73. Localizing templates
  74. --------------------
  75. Most importantly, this plugin can use localized templates for each
  76. sub-site. There are two approaches to having the templates localized:
  77. - You can set a different ``THEME`` override for each language in
  78. ``I18N_SUBSITES``, e.g. by making a copy of a theme ``my_theme`` to
  79. ``my_theme_lang`` and then editing the templates in the new
  80. localized theme. This approach means you don't have to deal with
  81. gettext ``*.po`` files, but it is harder to maintain over time.
  82. - You use only one theme and localize the templates using the
  83. `jinja2.ext.i18n Jinja2 extension
  84. <http://jinja.pocoo.org/docs/templates/#i18n>`_. For a kickstart
  85. read this `guide <./localizing_using_jinja2.rst>`_.
  86. Additional context variables
  87. ............................
  88. It may be convenient to add language buttons to your theme in addition
  89. to the translation links of articles and pages. These buttons could,
  90. for example, point to the ``SITEURL`` of each (sub-)site. For this
  91. reason the plugin adds these variables to the template context:
  92. ``main_lang``
  93. The language of the main site — the original ``DEFAULT_LANG``
  94. ``main_siteurl``
  95. The ``SITEURL`` of the main site — the original ``SITEURL``
  96. ``lang_siteurls``
  97. An ordered dictionary, mapping all used languages to their
  98. ``SITEURL``. The ``main_lang`` is the first key with ``main_siteurl``
  99. as the value. This dictionary is useful for implementing global
  100. language buttons that show the language of the currently viewed
  101. (sub-)site too.
  102. ``extra_siteurls``
  103. An ordered dictionary, subset of ``lang_siteurls``, the current
  104. ``DEFAULT_LANG`` of the rendered (sub-)site is not included, so for
  105. each (sub-)site ``set(extra_siteurls) == set(lang_siteurls) -
  106. set([DEFAULT_LANG])``. This dictionary is useful for implementing
  107. global language buttons that do not show the current language.
  108. ``relpath_to_site``
  109. A function that returns a relative path from the first (sub-)site to
  110. the second (sub-)site where the (sub-)sites are identified by the
  111. language codes given as two arguments.
  112. If you don't like the default ordering of the ordered dictionaries,
  113. use a Jinja2 filter to alter the ordering.
  114. All the siteurls above are always absolute even in the case of
  115. ``RELATIVE_URLS == True`` (it would be to complicated to replicate the
  116. Pelican internals for local siteurls), so you may rather use something
  117. like ``{{ SITEURL }}/{{ relpath_to_site(DEFAULT_LANG, main_lang }}``
  118. to link to the main site.
  119. This short `howto <./implementing_language_buttons.rst>`_ shows two
  120. example implementations of language buttons.
  121. Usage notes
  122. ===========
  123. - It is **mandatory** to specify ``lang`` metadata for each article
  124. and page as ``DEFAULT_LANG`` is later changed for each sub-site, so
  125. content without ``lang`` metadata would be rendered in every
  126. (sub-)site.
  127. - As with the original translations functionality, ``slug`` metadata
  128. is used to group translations. It is therefore often convenient to
  129. compensate for this by overriding the content URL (which defaults to
  130. slug) using the ``url`` and ``save_as`` metadata. You could also
  131. give articles e.g. ``name`` metadata and use it in ``ARTICLE_URL =
  132. '{name}.html'``.
  133. Development
  134. ===========
  135. - A demo and a test site is in the ``gh-pages`` branch and can be seen
  136. at http://smartass101.github.io/pelican-plugins/