8
0
Просмотр исходного кода

Docs: Locale and translation service API docs corrected. [skip ci]

Anna Tomanek 5 лет назад
Родитель
Сommit
7fd14b356b

+ 10 - 10
packages/ckeditor5-utils/src/locale.js

@@ -18,8 +18,8 @@ const RTL_LANGUAGE_CODES = [ 'ar', 'fa', 'he', 'ku', 'ug' ];
  */
 export default class Locale {
 	/**
-	 * Creates a new instance of the Locale class. Learn more about
-	 * {@glink features/ui-language configuring language of the editor}.
+	 * Creates a new instance of the locale class. Learn more about
+	 * {@glink features/ui-language configuring the language of the editor}.
 	 *
 	 * @param {Object} [options] Locale configuration.
 	 * @param {String} [options.uiLanguage='en'] The editor UI language code in the
@@ -43,7 +43,7 @@ export default class Locale {
 		/**
 		 * The editor content language code in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format.
 		 *
-		 * Usually the same as {@link #uiLanguage editor language}, it can be customized by passing an optional
+		 * Usually the same as the {@link #uiLanguage editor language}, it can be customized by passing an optional
 		 * argument to the `Locale` constructor.
 		 *
 		 * @readonly
@@ -77,9 +77,9 @@ export default class Locale {
 
 		/**
 		 * Translates the given message to the {@link #uiLanguage}. This method is also available in
-		 * {@link module:core/editor/editor~Editor#t Editor} and {@link module:ui/view~View#t View}.
+		 * {@link module:core/editor/editor~Editor#t `Editor`} and {@link module:ui/view~View#t `View`}.
 		 *
-		 * This method's context is statically bound to the `Locale` instance and **always should be called as a function**:
+		 * This method's context is statically bound to the `Locale` instance and **should always be called as a function**:
 		 *
 		 *		const t = locale.t;
 		 *		t( 'Label' );
@@ -87,7 +87,7 @@ export default class Locale {
 		 * The message can be either a string or an object implementing the {@link module:utils/translation-service~Message} interface.
 		 *
 		 * The message may contain placeholders (`%<index>`) for value(s) that are passed as a `values` parameter.
-		 * For an array of values the `%<index>` will be changed to an element of that array at the given index.
+		 * For an array of values, the `%<index>` will be changed to an element of that array at the given index.
 		 * For a single value passed as the second argument, only the `%0` placeholders will be changed to the provided value.
 		 *
 		 *		t( 'Created file "%0" in %1ms.', [ fileName, timeTaken ] );
@@ -105,7 +105,7 @@ export default class Locale {
 		 *		t( { string: 'Add a space', plural: 'Add %0 spaces' }, 5 ); // 'Dodaj 5 spacji' for the Polish language.
 		 *		t( { string: '%1 a space', plural: '%1 %0 spaces' }, [ 2, 'Add' ] ); // 'Dodaj 2 spacje' for the Polish language.
 		 *
-		 *  * The message should provide an id using the `id` property when the message strings are not unique and their
+		 *  * The message should provide an ID using the `id` property when the message strings are not unique and their
 		 * translations should be different.
 		 *
 		 *		translate( 'en', { string: 'image', id: 'ADD_IMAGE' } );
@@ -123,7 +123,7 @@ export default class Locale {
 	/**
 	 * The editor UI language code in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) format.
 	 *
-	 * **Note**: This property has been deprecated. Please use {@link #uiLanguage} and {@link #contentLanguage}
+	 * **Note**: This property was deprecated. Please use {@link #uiLanguage} and {@link #contentLanguage}
 	 * properties instead.
 	 *
 	 * @deprecated
@@ -131,8 +131,8 @@ export default class Locale {
 	 */
 	get language() {
 		/**
-		 * The {@link module:utils/locale~Locale#language `Locale#language`} property has been deprecated and will
-		 * be removed in the near future. Please use {@link #uiLanguage} and {@link #contentLanguage} properties instead.
+		 * The {@link module:utils/locale~Locale#language `Locale#language`} property was deprecated and will
+		 * be removed in the near future. Please use the {@link #uiLanguage} and {@link #contentLanguage} properties instead.
 		 *
 		 * @error locale-deprecated-language-property
 		 */

+ 28 - 28
packages/ckeditor5-utils/src/translation-service.js

@@ -20,15 +20,15 @@ if ( !window.CKEDITOR_TRANSLATIONS ) {
  * Adds translations to existing ones or overrides the existing translations. These translations will later
  * be available for the {@link module:utils/locale~Locale#t `t()`} function.
  *
- * The `translations` is an object which consists of a `messageId: translation` pairs. Note that the message id can be
- * either constructed from the message string or from the message id if it was passed
+ * The `translations` is an object which consists of `messageId: translation` pairs. Note that the message ID can be
+ * either constructed from the message string or from the message ID if it was passed
  * (this happens rarely and mostly for short messages or messages with placeholders).
- * Since the editor displays only the message string, the message id can be found either in the source code or in the
+ * Since the editor displays only the message string, the message ID can be found either in the source code or in the
  * built translations for another language.
  *
  *		add( 'pl', {
  *			'Cancel': 'Anuluj',
- *			'IMAGE': 'obraz', // Note that the `IMAGE` comes from the message id, while the string can be `image`.
+ *			'IMAGE': 'obraz', // Note that the `IMAGE` comes from the message ID, while the string can be `image`.
  *		} );
  *
  * If the message is supposed to support various plural forms, make sure to provide an array with the singular form and all plural forms:
@@ -37,10 +37,10 @@ if ( !window.CKEDITOR_TRANSLATIONS ) {
  *	 		'Add space': [ 'Dodaj spację', 'Dodaj %0 spacje', 'Dodaj %0 spacji' ]
  * 		} );
  *
- * You should also specify the third argument (the `getPluralForm` function) that will be used to determine the plural form if no
+ * You should also specify the third argument (the `getPluralForm()` function) that will be used to determine the plural form if no
  * language file was loaded for that language. All language files coming from CKEditor 5 sources will have this option set, so
- * these plural form rules will be reused by other translations added to the registered languages. The `getPluralForm` function
- * can return either a boolean or a number.
+ * these plural form rules will be reused by other translations added to the registered languages. The `getPluralForm()` function
+ * can return either a Boolean or a number.
  *
  * 		add( 'en', {
  *	 		// ... Translations.
@@ -60,10 +60,10 @@ if ( !window.CKEDITOR_TRANSLATIONS ) {
  *				// A function that returns the plural form index.
  *				getPluralForm: n => n !==1
  *			}
- *			// other languages.
+ *			// Other languages.
  *		}
  *
- * If you cannot import this function from this module (e.g. because you use a CKEditor 5 build), then you can
+ * If you cannot import this function from this module (e.g. because you use a CKEditor 5 build), you can
  * still add translations by extending the global `window.CKEDITOR_TRANSLATIONS` object by using a function like
  * the one below:
  *
@@ -87,7 +87,7 @@ if ( !window.CKEDITOR_TRANSLATIONS ) {
  *
  * @param {String} language Target language.
  * @param {Object.<String,*>} translations An object with translations which will be added to the dictionary.
- * For each message id the value should be either a translation or an array of translations if the message
+ * For each message ID the value should be either a translation or an array of translations if the message
  * should support plural forms.
  * @param {Function} getPluralForm A function that returns the plural form index (a number).
  */
@@ -105,25 +105,25 @@ export function add( language, translations, getPluralForm ) {
 }
 
 /**
- * **Note:** this method is internal, use {@link module:utils/locale~Locale#t the `t()` function} instead to translate
- * editor UI parts.
+ * **Note:** This method is internal, use {@link module:utils/locale~Locale#t the `t()` function} instead to translate
+ * the editor UI parts.
  *
- * This function is responsible for translating messages to the specified language. It uses perviously added translations
- * by {@link module:utils/translation-service~add} (a translations dictionary and and the `getPluralForm` function
+ * This function is responsible for translating messages to the specified language. It uses translations added perviously
+ * by {@link module:utils/translation-service~add} (a translations dictionary and the `getPluralForm()` function
  * to provide accurate translations of plural forms).
  *
- * When no translation is defined in the dictionary or the dictionary doesn't exist this function returns
- * the original message string or message plural depending on the number of elements.
+ * When no translation is defined in the dictionary or the dictionary does not exist, this function returns
+ * the original message string or the message plural depending on the number of elements.
  *
  *		translate( 'pl', { string: 'Cancel' } ); // 'Cancel'
  *
- * The third optional argument is the number of elements, based on which the single form or one of plural forms
+ * The third optional argument is the number of elements, based on which the single form or one of the plural forms
  * should be picked when the message is supposed to support various plural forms.
  *
  * 		translate( 'en', { string: 'Add a space', plural: 'Add %0 spaces' }, 1 ); // 'Add a space'
  * 		translate( 'en', { string: 'Add a space', plural: 'Add %0 spaces' }, 3 ); // 'Add %0 spaces'
  *
- * The message should provide an id using the `id` property when the message strings are not unique and their
+ * The message should provide an ID using the `id` property when the message strings are not unique and their
  * translations should be different.
  *
  *		translate( 'en', { string: 'image', id: 'ADD_IMAGE' } );
@@ -132,15 +132,15 @@ export function add( language, translations, getPluralForm ) {
  * @protected
  * @param {String} language Target language.
  * @param {module:utils/translation-service~Message|String} message A message that will be translated.
- * @param {Number} [quantity] A number of elements for which a plural form should be picked from the target language dictionary.
+ * @param {Number} [quantity] The number of elements for which a plural form should be picked from the target language dictionary.
  * @returns {String} Translated sentence.
  */
 export function _translate( language, message, quantity = 1 ) {
 	if ( typeof quantity !== 'number' ) {
 		/**
-		 * The incorrect value has been passed to the `translation` function. This probably was caused
-		 * by the incorrect message interpolation of a plural form. Note that for messages supporting plural forms
-		 * the second argument of the `t()` function should always be a number or an array with number as the first element.
+		 * An incorrect value was passed to the translation function. This was probably caused
+		 * by an incorrect message interpolation of a plural form. Note that for messages supporting plural forms
+		 * the second argument of the `t()` function should always be a number or an array with a number as the first element.
 		 *
 		 * @error translation-service-quantity-not-a-number
 		 */
@@ -202,15 +202,15 @@ function getNumberOfLanguages() {
 
 /**
  * The internationalization message interface. A message that implements this interface can be passed to the `t()` function
- * to be translated to the target ui language.
+ * to be translated to the target UI language.
  *
  * @typedef {Object} module:utils/translation-service~Message
  *
- * @property {String} string The message string to translate. Acts as a default translation if the translation for given language
- * is not defined. When the message is supposed to support plural forms then the string should be the English singular form of the message.
- * @property {String} [id] The message id. If passed then the message id is taken from this property instead of the `message.string`.
- * This property is useful when various messages share the same message string. E.g. `editor` string in `in the editor` and `my editor`
- * sentences.
+ * @property {String} string The message string to translate. Acts as a default translation if the translation for a given language
+ * is not defined. When the message is supposed to support plural forms, the string should be the English singular form of the message.
+ * @property {String} [id] The message ID. If passed, the message ID is taken from this property instead of the `message.string`.
+ * This property is useful when various messages share the same message string, for example, the `editor` string in `in the editor`
+ * and `my editor` sentences.
  * @property {String} [plural] The plural form of the message. This property should be skipped when a message is not supposed
  * to support plural forms. Otherwise it should always be set to a string with the English plural form of the message.
  */