<commit_before>require 'zen/language/translation'

module Zen
  ##
  # ``Zen::Language`` is the heart of the multi language system that comes with
  # Zen. It makes it easy to display localized bits of text as well as adding
  # new collections of translated strings.
  #
  # ## Adding Languages
  #
  # Adding a new language can be done by using {Zen::Language.add}. This method
  # works similar to the ones used by {Zen::Package} and {Zen::Theme}. An
  # example of adding a language (English in this case) looks like the
  # following:
  #
  #     Zen::Language.add do |lang|
  #       lang.name  = 'en'
  #       lang.title = 'English'
  #     end
  #
  # When adding a language you **must** set the following items:
  #
  # * **name**: the language code as defined in [ISO 639][iso 639]. Examples of
  #   these codes are "en-GB", "nl", etc. At the moment Zen does not have
  #   different language files for British English and American English.
  # * **title**: the name of the language in a human friendly form. This name
  #   should be set in the specific language. For example, for Dutch the title
  #   would be "Nederlands".
  #
  # Optionally you can also set the following attributes:
  #
  # * **rtl**: indicates that the language reads from right to left. When set to
  #   true the ``<html>`` tag will have an extra ``dir`` attribute so that
  #   browsers can properly display the text from right to left.
  #
  # ## Adding Translations
  #
  # Translations for a certain language are added using
  # {Zen::Language::Translation}. Similar to languages these are added by
  # calling ``.add()``. A simple example of adding a set of translations is the
  # following:
  #
  #     Zen::Language::Translation.add do |trans|
  #       trans.language = 'en'
  #       trans.name     = 'foobar'
  #
  #       trans.translate do |t|
  #
  #       end
  #     end
  #
  # This adds a language collection called "foobar" for the English language.
  # Translation strings are added inside the block of the ``translate()``
  # method. Setting these strings works just like setting the keys and values of
  # a hash:
  #
  #     trans.translate do |t|
  #       t['hello'] = 'Hello World'
  #     end
  #
  # It is a good idea to group certain language strings together. For example,
  # you might have a few strings related to page titles. The way of doing this
  # is by simply separating groups with a dot in the keys:
  #
  #     trans.translate do |t|
  #       t['titles.index'] = 'Example'
  #       t['titles.edit']  = 'Edit Example'
  #     end
  #
  # The keys specified in ``[]=`` should match the regular expression as defined
  # in {Zen::Language::Translation::KEY_REGEX}. In plain English, they can only
  # contain lower case letters, underscores and dots.
  #
  # A full example:
  #
  #     Zen::Language::Translation.add do |trans|
  #       trans.language = 'en'
  #       trans.name     = 'foobar'
  #
  #       trans.translate do |t|
  #         t['titles.index'] = 'Example'
  #         t['titles.edit']  = 'Edit Example'
  #       end
  #     end
  #
  # ## Organizing Languages
  #
  # In order for language files to be loaded by Zen you need to place them in
  # certain directories using a certain file name. Language files should be
  # named after the ``name`` setter/getter defined when calling
  # {Zen::Language::Translation.add} (including casing) and should have ``.rb``
  # as extension. These files should be placed in sub directories that match the
  # language name they belong to. These directories in turn should be placed
  # inside a "language" directory.
  #
  # In other words, our "foobar" example would be stored as following:
  #
  #      language/
  #      |
  #      |__ en/
  #         |
  #         |__ foobar.rb
  #
  # Before you can load files from the language directory you'll need to add it
  # to the list of directories to search each time a language file is loaded.
  # Similar to how you can add view folders or helper folders in Ramaze you can
  # add language folders:
  #
  #     Zen::Language.options.paths << 'path/to/language'
  #
  # ## Loading Translations
  #
  # Once a language file has been added it must be loaded before it can be used.
  # Loading a language file can be done in two ways:
  #
  # 1. Manually loading it by calling {Zen::Language.load}.
  # 2. Calling {Zen::Language.lang} or ``lang()`` (injected into the global
  #    namespace).
  #
  # In the last case missing language files will be loaded if possible. However,
  # it is recommended that you pre-load your language files before starting the
  # application. By doing this these translations don't have to be loaded during
  # an HTTP request which could potentially slow down the application.
  #
  # If we wanted to load the "foobar" language file mentioned earlier you can do
  # this as following:
  #
  #     Zen::Language.load('foobar')
  #
  # ## Using Translations
  #
  # Once the entire process of adding and loading a language file has been
  # completed you can use the language strings defined in that file. This can be
  # done by calling the global method ``lang()`` which is available in all
  # scopes. If you happen to need it in a scope where it's overwritten you can
  # call {Zen::Language.lang} instead.
  #
  # A simple example of loading a few language strings of the file defined
  # earlier in this guide looks like this:
  #
  #     lang('foobar.titles.index')
  #
  # Language keys should **always** be in the format of ``A.B`` where A is the
  # name of the language file ("foobar" in this case) and B a dot separated
  # string that points to the language string to load. This means that the
  # following examples are not valid:
  #
  #     lang('foobar')
  #     lang('foo bar')
  #<commit_msg>Improved the documentation for Zen::Language.<commit_after>require 'zen/language/translation'

module Zen
  ##
  # ``Zen::Language`` is the heart of the multi language system that comes with
  # Zen. It makes it easy to display localized bits of text as well as adding
  # new collections of translated strings.
  #
  # ## Adding Languages
  #
  # Adding a new language can be done by using {Zen::Language.add}. This method
  # works similar to the ones used by {Zen::Package} and {Zen::Theme}. An
  # example of adding a language (English in this case) looks like the
  # following:
  #
  #     Zen::Language.add do |lang|
  #       lang.name  = 'en'
  #       lang.title = 'English'
  #     end
  #
  # When adding a language you **must** set the following items:
  #
  # * **name**: the language code as defined in [ISO 639][iso 639]. Examples of
  #   these codes are "en-GB", "nl", etc. At the moment Zen does not have
  #   different language files for British English and American English.
  # * **title**: the name of the language in a human friendly form. This name
  #   should be set in the specific language. For example, for Dutch the title
  #   would be "Nederlands".
  #
  # Optionally you can also set the following attributes:
  #
  # * **rtl**: indicates that the language reads from right to left. When set to
  #   true the ``<html>`` tag will have an extra ``dir`` attribute so that
  #   browsers can properly display the text from right to left.
  #
  # ## Adding Translations
  #
  # Translations for a certain language are added using
  # {Zen::Language::Translation}. Similar to languages these are added by
  # calling ``.add()``. A simple example of adding a set of translations is the
  # following:
  #
  #     Zen::Language::Translation.add do |trans|
  #       trans.language = 'en'
  #       trans.name     = 'foobar'
  #
  #       trans.translate do |t|
  #
  #       end
  #     end
  #
  # This adds a language collection called "foobar" for the English language.
  # Translation strings are added inside the block of the ``translate()``
  # method. Setting these strings works just like setting the keys and values of
  # a hash:
  #
  #     trans.translate do |t|
  #       t['hello'] = 'Hello World'
  #     end
  #
  # It is a good idea to group certain language strings together. For example,
  # you might have a few strings related to page titles. The way of doing this
  # is by simply separating groups with a dot in the keys:
  #
  #     trans.translate do |t|
  #       t['titles.index'] = 'Example'
  #       t['titles.edit']  = 'Edit Example'
  #     end
  #
  # The keys specified in ``[]=`` should match the regular expression as defined
  # in {Zen::Language::Translation::KEY_REGEX}. In plain English, they can only
  # contain lower case letters, underscores and dots.
  #
  # A full example:
  #
  #     Zen::Language::Translation.add do |trans|
  #       trans.language = 'en'
  #       trans.name     = 'foobar'
  #
  #       trans.translate do |t|
  #         t['titles.index'] = 'Example'
  #         t['titles.edit']  = 'Edit Example'
  #       end
  #     end
  #
  # ## Organizing Languages
  #
  # In order for language files to be loaded by Zen you need to place them in
  # certain directories using a certain file name. Language files should be
  # named after the ``name`` setter/getter defined when calling
  # {Zen::Language::Translation.add} (including casing) and should have ``.rb``
  # as extension. These files should be placed in sub directories that match the
  # language name they belong to. These directories in turn should be placed
  # inside a "language" directory.
  #
  # In other words, our "foobar" example would be stored as following:
  #
  #      language/
  #      |
  #      |__ en/
  #         |
  #         |__ foobar.rb
  #
  # Before you can load files from the language directory you'll need to add it
  # to the list of directories to search each time a language file is loaded.
  # Similar to how you can add view folders or helper folders in Ramaze you can
  # add language folders:
  #
  #     Zen::Language.options.paths << 'path/to/language'
  #
  # ## Loading Translations
  #
  # Once a language file has been added it must be loaded before it can be used.
  # Loading a language file can be done in two ways:
  #
  # 1. Manually loading it by calling {Zen::Language.load}.
  # 2. Calling {Zen::Language.lang} or ``lang()`` (injected into the global
  #    namespace).
  #
  # In the last case missing language files will be loaded if possible. However,
  # it is recommended that you pre-load your language files before starting the
  # application. By doing this these translations don't have to be loaded during
  # an HTTP request which could potentially slow down the application.
  #
  # If we wanted to load the "foobar" language file mentioned earlier you can do
  # this as following:
  #
  #     Zen::Language.load('foobar')
  #
  # Due to the way the language system works it's impossible to load these
  # before {Zen.start} is called. The recommended way of loading a language file
  # is by wrapping it in an event listener for the "post_start" event:
  #
  #     Zen::Event.listen :post_start do
  #       Zen::Language.load('example')
  #     end
  #
  # The reason for this requirement is that language files are stored in a cache
  # (Ramaze::Cache::LRU by default) and this cache isn't set up until
  # {Zen.start} is called.
  #
  # <div class="note todo">
  #     <p>
  #         This can't be stressed enough: always load language files using the
  #         post_start event.
  #     </p>
  # </div>
  #
  # ## Using Translations
  #
  # Once the entire process of adding and loading a language file has been
  # completed you can use the language strings defined in that file. This can be
  # done by calling the global method ``lang()`` which is available in all
  # scopes. If you happen to need it in a scope where it's overwritten you can
  # call {Zen::Language.lang} instead.
  #
  # A simple example of loading a few language strings of the file defined
  # earlier in this guide looks like this:
  #
  #     lang('foobar.titles.index')
  #
  # Language keys should **always** be in the format of ``A.B`` where A is the
  # name of the language file ("foobar" in this case) and B a dot separated
  # string that points to the language string to load. This means that the
  # following examples are not valid:
  #
  #     lang('foobar')
  #     lang('foo bar')
  #
  # <div class="note todo">
  #     <p>
  #         Because language files aren't loaded until Zen.start is called you
  #         should never use or rely on translations before the application has
  #         started. Most of the core code works around this by loading
  #         translations using blocks whenever they're needed.
  #     </p>
  # </div>
  #
{'fraction_non_alphanumeric': 0.09074367088607595, 'fraction_numerical': 0.0012658227848101266, 'mean_word_length': 2.7983774038461537, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4290511', 'n_tokens_mistral': 3704, 'n_tokens_neox': 3619, 'n_words': 1642}