i18n: Deprecate getI18n, dcnpgettext (#9485)

docs/reference/deprecated.md

@@ -4,6 +4,8 @@ Gutenberg's deprecation policy is intended to support backwards-compatibility fo
 
 - `wp.components.RichTextProvider` has been removed. Please use `wp.data.select( 'core/editor' )` methods instead.
 - `wp.components.Draggable` as a DOM node drag handler has been removed. Please, use `wp.components.Draggable` as a wrap component for your DOM node drag handler.
+- `wp.i18n.getI18n` has been removed. Use `__`, `_x`, `_n`, or `_nx` instead.
+- `wp.i18n.dcnpgettext` has been removed. Use `__`, `_x`, `_n`, or `_nx` instead.
 
 ## 3.9.0
 

lib/client-assets.php

@@ -144,7 +144,7 @@ function gutenberg_register_scripts_and_styles() {
 	wp_register_script(
 		'wp-i18n',
 		gutenberg_url( 'build/i18n/index.js' ),
-		array(),
+		array( 'wp-deprecated' ),
 		filemtime( gutenberg_dir_path() . 'build/i18n/index.js' ),
 		true
 	);

packages/i18n/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 2.1.0 (Unreleased)
+
+### Deprecations
+
+- `getI18n` has been deprecated. Use `__`, `_x`, `_n`, or `_nx` instead.
+- `dcnpgettext` has been deprecated. Use `__`, `_x`, `_n`, or `_nx` instead.
+
 ## 2.0.0 (2018-09-05)
 
 ### Breaking Change

packages/i18n/README.md

@@ -71,10 +71,4 @@ See: http://www.diveintojavascript.com/projects/javascript-sprintf
 
 Creates a new Jed instance with specified locale data configuration.
 
-`getI18n(): Jed`
-
-Returns the current Jed instance, initializing with a default configuration if not already assigned.
-
-See: http://messageformat.github.io/Jed/
-
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/i18n/package.json

@@ -23,6 +23,7 @@
 	},
 	"dependencies": {
 		"@babel/runtime": "^7.0.0",
+		"@wordpress/deprecated": "file:../deprecated",
 		"gettext-parser": "^1.3.1",
 		"jed": "^1.1.1",
 		"lodash": "^4.17.10",

packages/i18n/src/index.js

@@ -4,6 +4,11 @@
 import Jed from 'jed';
 import memoize from 'memize';
 
+/**
+ * WordPress dependencies
+ */
+import deprecated from '@wordpress/deprecated';
+
 let i18n;
 
 /**
@@ -47,7 +52,7 @@ export function setLocaleData( localeData = { '': {} }, domain = 'default' ) {
  *
  * @return {Jed} Jed instance.
  */
-export function getI18n() {
+function _getI18n() {
 	if ( ! i18n ) {
 		setLocaleData();
 	}
@@ -69,9 +74,9 @@ export function getI18n() {
  *
  * @return {string} The translated string.
  */
-export const dcnpgettext = memoize( ( domain = 'default', context, single, plural, number ) => {
+const _dcnpgettext = memoize( ( domain = 'default', context, single, plural, number ) => {
 	try {
-		return getI18n().dcnpgettext( domain, context, single, plural, number );
+		return _getI18n().dcnpgettext( domain, context, single, plural, number );
 	} catch ( error ) {
 		logErrorOnce( 'Jed localization error: \n\n' + error.toString() );
 
@@ -90,7 +95,7 @@ export const dcnpgettext = memoize( ( domain = 'default', context, single, plura
  * @return {string} Translated text.
  */
 export function __( text, domain ) {
-	return dcnpgettext( domain, undefined, text );
+	return _dcnpgettext( domain, undefined, text );
 }
 
 /**
@@ -105,7 +110,7 @@ export function __( text, domain ) {
  * @return {string} Translated context string without pipe.
  */
 export function _x( text, context, domain ) {
-	return dcnpgettext( domain, context, text );
+	return _dcnpgettext( domain, context, text );
 }
 
 /**
@@ -123,7 +128,7 @@ export function _x( text, context, domain ) {
  * @return {string} The translated singular or plural form.
  */
 export function _n( single, plural, number, domain ) {
-	return dcnpgettext( domain, undefined, single, plural, number );
+	return _dcnpgettext( domain, undefined, single, plural, number );
 }
 
 /**
@@ -142,7 +147,7 @@ export function _n( single, plural, number, domain ) {
  * @return {string} The translated singular or plural form.
  */
 export function _nx( single, plural, number, context, domain ) {
-	return dcnpgettext( domain, context, single, plural, number );
+	return _dcnpgettext( domain, context, single, plural, number );
 }
 
 /**
@@ -165,3 +170,31 @@ export function sprintf( format, ...args ) {
 		return format;
 	}
 }
+
+//
+// Deprecated
+//
+
+// TODO: Revert names of internal copies to non-underscore-prefixed, as it is
+// only needed to avoid variable shadowing issues with deprecated version on
+// the exported public interface.
+
+export function getI18n() {
+	deprecated( 'wp.i18n.getI18n', {
+		plugin: 'Gutenberg',
+		version: '4.0',
+		alternative: '`__`, `_x`, `_n`, or `_nx`',
+	} );
+
+	return _getI18n();
+}
+
+export function dcnpgettext( domain, context, single, plural, number ) {
+	deprecated( 'wp.i18n.dcnpgettext', {
+		plugin: 'Gutenberg',
+		version: '4.0',
+		alternative: '`__`, `_x`, `_n`, or `_nx`',
+	} );
+
+	return _dcnpgettext( domain, context, single, plural, number );
+}

packages/i18n/src/test/index.js

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import { dcnpgettext, sprintf, __, _x, _n, _nx, setLocaleData } from '../';
+import { sprintf, __, _x, _n, _nx, setLocaleData } from '../';
 
 // Mock memoization as identity function. Inline since Jest errors on out-of-
 // scope references in a mock callback.
@@ -34,12 +34,25 @@ const additionalLocaleData = {
 setLocaleData( localeData, 'test_domain' );
 
 describe( 'i18n', () => {
-	describe( 'dcnpgettext()', () => {
-		it( 'absorbs errors', () => {
-			const result = dcnpgettext( 'domain-without-data', undefined, 'Hello' );
+	describe( 'error absorb', () => {
+		it( '__', () => {
+			__( 'Hello', 'domain-without-data' );
+			expect( console ).toHaveErrored();
+		} );
+
+		it( '_x', () => {
+			_x( 'feed', 'verb', 'domain-without-data' );
+			expect( console ).toHaveErrored();
+		} );
+
+		it( '_n', () => {
+			_n( '%d banana', '%d bananas', 3, 'domain-without-data' );
+			expect( console ).toHaveErrored();
+		} );
 
+		it( '_nx', () => {
+			_nx( '%d apple', '%d apples', 3, 'fruit', 'domain-without-data' );
 			expect( console ).toHaveErrored();
-			expect( result ).toBe( 'Hello' );
 		} );
 	} );