     @deepMerge @locales, yaml.load content for path, content of docs
     @languages = @locales.sortedKeys()
 
+  ##### I18n::deepMerge
+
+  # Merge two tree structures formed by nested objects into one tree structure.
+  #
+  #     source =
+  #       foo:
+  #         bar: 10
+  #     target =
+  #       foo:
+  #         baz: 20
+  #     deepMerge target, source
+  #     # target = {foo: {bar: 10, baz: 20}}
   deepMerge: (target, source) ->
     for k,v of source
       switch typeof v

  # Returns a string from the locales.
  # That function can be called either with or without a language:
  #
  #     i18n
  get: (language, path) ->
    [language, path] = [@defaultLanguage, language] unless path?
    lang = @locales[language]

    lang = els.last().replace(/[-_]/g, ' ').capitalizeAll() unless lang?
    lang

  ##### I18n::getHelper

  # Returns a helper function bound to the current instance that allow
  # to retrieve localized string from the `I18n` instance as well as doing
  # token substitution in the returned string.
  #
  #     _ = i18n.getHelper()
  #     _('path.to.string')
  #     _('path.to.string_with_token', token: 'token substitute')
  getHelper: -> (path, tokens) =>
    @get(path).replace /\#\{([^\}]+)\}/g, (token, key) -> tokens[key] or token

  ##### I18n::load

  # Search and loads locales files in the given paths, parse their content
  # and fill the `locales` object with the resuts.
  load: ->
    @locales = {}
    docs = readFilesSync findSync 'yml', @paths
