diff --git a/entity/tmgmt.entity.translator.inc b/entity/tmgmt.entity.translator.inc
index 9666428..21845f5 100644
--- a/entity/tmgmt.entity.translator.inc
+++ b/entity/tmgmt.entity.translator.inc
@@ -261,6 +261,8 @@ class TMGMTTranslator extends Entity {
    *
    * @return string
    *   Remote language code.
+   *
+   * @ingroup tmgmt_remote_languages_mapping
    */
   public function mapToRemoteLanguage($language) {
     return $this->getController()->mapToRemoteLanguage($this, $language);
@@ -274,6 +276,8 @@ class TMGMTTranslator extends Entity {
    *
    * @return string
    *   Local language code.
+   *
+   * @ingroup tmgmt_remote_languages_mapping
    */
   public function mapToLocalLanguage($language) {
     return $this->getController()->mapToLocalLanguage($this, $language);
diff --git a/plugin/tmgmt.plugin.interface.translator.inc b/plugin/tmgmt.plugin.interface.translator.inc
index d56796f..929563c 100644
--- a/plugin/tmgmt.plugin.interface.translator.inc
+++ b/plugin/tmgmt.plugin.interface.translator.inc
@@ -65,31 +65,47 @@ interface TMGMTTranslatorPluginControllerInterface extends TMGMTPluginBaseInterf
   /**
    * Specifies default mappings for local to remote language codes.
    *
+   * This method can be used in case we know in advance what language codes are
+   * used by the remote translator and to which local language codes they
+   * correspond.
+   *
    * @return array
    *   An array of local => remote language codes.
+   *
+   * @ingroup tmgmt_remote_languages_mapping
    */
   public function getDefaultRemoteLanguagesMappings();
 
   /**
    * Gets all supported languages of the translator.
    *
+   * This list of all language codes used by the remote translator is then used
+   * for example in the translator settings form to select which remote language
+   * code correspond to which local language code.
+   *
    * @param TMGMTTranslator $translator
    *   Translator entity for which to get supported languages.
    *
    * @return array
    *   An array of language codes which are provided by the translator
    *   (remote language codes).
+   *
+   * @ingroup tmgmt_remote_languages_mapping
    */
   public function getSupportedRemoteLanguages(TMGMTTranslator $translator);
 
   /**
    * Gets existing remote languages mappings.
    *
+   * This method is responsible to provide all local to remote language pairs.
+   *
    * @param TMGMTTranslator $translator
    *   Translator entity for which to get mappings.
    *
    * @return array
    *   An array of local => remote language codes.
+   *
+   * @ingroup tmgmt_remote_languages_mapping
    */
   public function getRemoteLanguagesMappings(TMGMTTranslator $translator);
 
@@ -103,6 +119,8 @@ interface TMGMTTranslatorPluginControllerInterface extends TMGMTPluginBaseInterf
    *
    * @return string
    *   Remote language code.
+   *
+   * @ingroup tmgmt_remote_languages_mapping
    */
   public function mapToRemoteLanguage(TMGMTTranslator $translator, $language);
 
@@ -116,6 +134,8 @@ interface TMGMTTranslatorPluginControllerInterface extends TMGMTPluginBaseInterf
    *
    * @return string
    *   Local language code.
+   *
+   * @ingroup tmgmt_remote_languages_mapping
    */
   public function mapToLocalLanguage(TMGMTTranslator $translator, $language);
 
@@ -130,6 +150,8 @@ interface TMGMTTranslatorPluginControllerInterface extends TMGMTPluginBaseInterf
    *
    * @return array
    *   An array of remote languages in ISO format.
+   *
+   * @ingroup tmgmt_remote_languages_mapping
    */
   public function getSupportedTargetLanguages(TMGMTTranslator $translator, $source_language);
 
@@ -150,6 +172,8 @@ interface TMGMTTranslatorPluginControllerInterface extends TMGMTPluginBaseInterf
    *     array('source_language' => 'en-US', 'target_language' => 'de-DE'),
    *     array('source_language' => 'en-US', 'target_language' => 'de-CH'),
    *   )
+   *
+   * @ingroup tmgmt_remote_languages_mapping
    */
   public function getSupportedLanguagePairs(TMGMTTranslator $translator);
 
@@ -160,6 +184,8 @@ interface TMGMTTranslatorPluginControllerInterface extends TMGMTPluginBaseInterf
    *
    * @param TMGMTJob $job
    *   The job that should be submitted.
+   *
+   * @ingroup tmgmt_remote_languages_mapping
    */
   public function requestTranslation(TMGMTJob $job);
 
diff --git a/tmgmt.api.php b/tmgmt.api.php
index 85bd77f..90fbfb6 100644
--- a/tmgmt.api.php
+++ b/tmgmt.api.php
@@ -201,3 +201,59 @@ function hook_tmgmt_translator_plugin_info_alter(&$info) {
  *   sources in their implementation of
  *   TMGMTSourcePluginControllerInterface::saveTranslation().
  */
+
+/**
+ * @defgroup tmgmt_remote_languages_mapping Remote languages mapping
+ *
+ * Logic to deal with different language codes at client and server that stand
+ * for the same language.
+ *
+ * Each tmgmt plugin is expected to support this feature. However for those
+ * plugins where such feature has no use there is a plugin setting
+ * "map remote languages" which can be set to FALSE.
+ *
+ * @section mappings_info Mappings info
+ *
+ * There are several methods defined by
+ * TMGMTTranslatorPluginControllerInterface and implemented in
+ * TMGMTDefaultTranslatorPluginController that deal with mappings info.
+ *
+ * - getRemoteLanguagesMappings() - provides pairs of local_code => remote_code.
+ * - mapToRemoteLanguage() & mapToLocalLanguage() - helpers to map local/remote.
+ *   Note that methods with same names and functionality are provided by the
+ *   TMGMTTranslator entity. These are convenience methods.
+ *
+ * The above methods should not need reimplementation unless special logic is
+ * needed. However following methods provide only the fallback behaviour and
+ * therefore it is recommended that each plugin provides its specific
+ * implementation.
+ *
+ * - getDefaultRemoteLanguagesMappings() - we might know some mapping pairs
+ *   prior to configuring a plugin, this is the place where we can define these
+ *   mappings. The default implementation returns an empty array.
+ * - getSupportedRemoteLanguages() - gets array of language codes in lang_code =>
+ *   lang_code format. It says with what languages the remote system can deal
+ *   with. These codes are in the remote format.
+ *
+ * @section mapping_remote_to_local Mapping remote to local
+ *
+ * Mapping remote to local language codes is done when determining the
+ * language capabilities of the remote system. All following logic should then
+ * solely work with local language codes. There are two methods defined by
+ * the TMGMTTranslatorPluginControllerInterface interface. To do the mapping
+ * a plugin must implement getSupportedTargetLanguages().
+ *
+ * - getSupportedTargetLanguages() - should return local language codes. So
+ *   within this method the mapping needs to be executed.
+ * - getSupportedLanguagePairs() - gets language pairs for which translations
+ *   can be done. The language codes must be in local form. The default
+ *   implementation uses getSupportedTargetLanguages() so mapping occur. However
+ *   this approach is not effective and therefore each plugin should provide
+ *   its specific implementation with regard to performance.
+ *
+ * @section mapping_local_to_remote Mapping local to remote
+ *
+ * Mapping of local to remote language codes is done upon translation job
+ * request in the TMGMTTranslatorPluginControllerInterface::requestTranslation()
+ * plugin implementation.
+ */