diff --git a/docs/index.rst b/docs/index.rst index fa90db8c..ba511f5e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -86,6 +86,11 @@ The basic usage is like this: languageData.getAutonym( 'en'); // Returns version of the language data or UNKNOWN if not declared languageData.getVersion(); + // Returns an object mapping all territory codes to their language arrays + // e.g. { US: ['en', 'es', ...], DE: ['de'], ... } + languageData.getTerritoriesWithLanguages(); + // Returns the languages spoken in a specific territory + languageData.getLanguagesInTerritory( 'US' ); The exposed methods are similar to the methods present in the PHP `LanguageUtil `_ class. diff --git a/src/LanguageUtil.php b/src/LanguageUtil.php index 692ef246..1fe6765d 100644 --- a/src/LanguageUtil.php +++ b/src/LanguageUtil.php @@ -7,6 +7,8 @@ namespace Wikimedia\LanguageData; +use stdClass; + /** * A singleton utility class to query the language data. */ @@ -365,6 +367,15 @@ public function getDir( string $languageCode ) { return false; } + /** + * Returns all territories and the languages spoken in each. + * @return stdClass An object whose keys are territory codes and whose values + * are arrays of language codes spoken in that territory. + */ + public function getTerritoriesWithLanguages(): stdClass { + return $this->data->territories; + } + /** * Returns the languages spoken in a territory * @param string $territory Territory code diff --git a/src/index.js b/src/index.js index 1ba2a3aa..8d81c2d2 100644 --- a/src/index.js +++ b/src/index.js @@ -284,6 +284,16 @@ function getDir( language ) { return isRtl( language ) ? 'rtl' : 'ltr'; } +/** + * Returns all territories and the languages spoken in each. + * + * @return {Object} An object whose keys are territory codes and whose values + * are arrays of language codes spoken in that territory. + */ +function getTerritoriesWithLanguages() { + return languageData.territories; +} + /** * Returns the languages spoken in a territory. * @@ -328,6 +338,7 @@ module.exports = { getRegionGroups, getScript, getScriptGroupOfLanguage, + getTerritoriesWithLanguages, isKnown, isRedirect, isRtl, diff --git a/tests/js/index.js b/tests/js/index.js index d3ed4a8d..ed67127e 100644 --- a/tests/js/index.js +++ b/tests/js/index.js @@ -151,6 +151,14 @@ describe( 'languagedata', () => { 'An invalid country has no languages and returns an empty array' ); + const territories = languageData.getTerritoriesWithLanguages(); + assert.ok( typeof territories === 'object' && territories !== null, 'getTerritoriesWithLanguages() returns an object' ); + assert.ok( Array.isArray( territories[ 'US' ] ), 'US territory entry is an array' ); + assert.ok( territories[ 'US' ].includes( 'en' ), 'English is listed for the US territory' ); + assert.ok( territories[ 'RU' ].includes( 'sah' ), 'Sakha is listed for the RU territory via getTerritoriesWithLanguages()' ); + assert.ok( Object.keys( territories ).length > 0, 'getTerritoriesWithLanguages() returns a non-empty set of territories' ); + assert.strictEqual( territories[ 'no-such-country' ], undefined, 'An invalid territory code is not present in getTerritoriesWithLanguages()' ); + const languagesAM = [ 'atj', 'chr', 'chy', 'cr', 'en', 'es', 'fr', 'gn', 'haw', 'ike-cans', 'ik', 'kl', 'nl', 'pt', 'qu', 'srn', 'yi' ]; assert.deepEqual( languageData.sortByScriptGroup( languagesAM.sort( languageData.sortByAutonym ) ), diff --git a/tests/php/LanguageUtilTest.php b/tests/php/LanguageUtilTest.php index eec2603b..658ec8f9 100644 --- a/tests/php/LanguageUtilTest.php +++ b/tests/php/LanguageUtilTest.php @@ -198,6 +198,28 @@ public function testGetLanguagesInTerritory() { $this->assertNotContains( 'de', $actualsAFG ); } + public function testGetTerritoriesWithLanguages() { + $territories = $this->languageUtil->getTerritoriesWithLanguages(); + + $this->assertObjectHasProperty( 'US', $territories, 'US is a known territory' ); + $this->assertContains( 'en', $territories->US, 'English is listed for the US territory' ); + + $this->assertObjectHasProperty( 'AT', $territories, 'AT is a known territory' ); + $this->assertContains( 'de', $territories->AT, 'German is listed for the AT territory' ); + + $this->assertObjectNotHasProperty( + 'no-such-country', + $territories, + 'An invalid territory code is not present in getTerritoriesWithLanguages()' + ); + + $this->assertGreaterThan( + 0, + count( (array)$territories ), + 'getTerritoriesWithLanguages() returns a non-empty set of territories' + ); + } + public function testAddLanguage() { $this->assertFalse( $this->languageUtil->isKnown( 'xyz' ) ); $this->assertNotContains(