@streetcredlabs/categories - npm Package Compare versions

Comparing version 3.2.1 to 3.3.0

dist/index.d.ts

@@ -38,3 +38,3 @@ export interface IFlattenedCategory {
  */
-export declare const dump: (language?: Languages) => ICategory[];
+export declare const dump: (language?: Languages, sortAlphabetically?: boolean) => ICategory[];
 /**
@@ -44,4 +44,8 @@ * find a single category by id
 export declare const findById: (catId: number, language?: Languages) => IFlattenedCategory | undefined;
+/**
+ * Sorts categories alphabetically based on category name in locale
+ */
+export declare const sortCategories: (cats: ICategory[], collator: Intl.Collator) => ICategory[];
 export declare const flatten: (cats: ICategory[]) => IFlattenedCategoriesById;
 export declare const getCompleteness: (place: import("./utils/getCompleteness").IPlace) => number;
 export {};

package.json

 {
   "name": "@streetcredlabs/categories",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "JS utility wrapper for places category taxonomy",
@@ -5,0 +5,0 @@ "repository": {

README.md

@@ -29,2 +29,4 @@ # Categories [![Build Status](https://travis-ci.com/streetcredlabs/categories.svg?token=kd4tyu6APW8yEuYYcqLi&branch=master)](https://travis-ci.com/streetcredlabs/categories)
 
+The following top-level exports are available:
+
 ### Languages
@@ -34,2 +36,10 @@
 
+```js
+> const cats = require('./dist/bundle')
+undefined
+> `The following languages are available: ${Object.keys(cats.Languages).join(', ')}`
+'The following languages are available: en, fil, id, ms, th, vi, zh-Hans'
+
+```
+
 ### findById
@@ -63,2 +73,7 @@
 
+Parameters:
+
+* `language` (defaults to `en`): one of the available language codes found in the `Languages` enum
+* `sortAlphabetically` (defaults to `true`): whether or not to sort categories using a language-aware sorter
+
 Returns the entire categories array.
@@ -85,2 +100,4 @@
 
+
+
 ### getCompleteness
@@ -102,2 +119,69 @@
 
+## Translations
+
+This project uses [`lingui`](https://github.com/lingui/js-lingui/) to generate gettext-format `.po` files containing all of the category names.
+
+### Adding a new language
+
+As an example, here's how to add a translation for the language Ido, which uses the code `io`.
+
+The first step to add a new translation is to use `lingui` to add a new locale and extract existing strings:
+
+```
+yarn lingui add-locale io
+yarn lingui extract io
+```
+
+The first command will create a stub translation file in `src/locales/io/messages.po` and the second command will append all translatable strings into that file. Provide a translator with the `messages.po`, and have them fill in the `msgstr ""`s with translations of the preceeding `msgid "..."`s.
+
+Once all of the translations are done, transform the `po`-file into the Lingui format:
+
+```
+yarn lingui compile --typescript
+```
+
+Include the completed translation in the library by adding it to `src/index.ts`:
+
+```diff
+diff --git a/src/index.ts b/src/index.ts
+index e260261..7ad39f6 100644
+--- a/src/index.ts
++++ b/src/index.ts
+@@ -7,6 +7,7 @@ import ms from './locales/ms/messages';
+ import th from './locales/th/messages';
+ import vi from './locales/vi/messages';
+ import zhHans from './locales/zh-Hans/messages';
++import io from './locales/io/messages';
+
+ import categories from './data/categories';
+ import getCompletenessUtil from './utils/getCompleteness';
+@@ -20,6 +21,7 @@ const catalogs = {
+   th,
+   vi,
+   'zh-Hans': zhHans,
++  io,
+ };
+
+ // Some shared types
+```
+
+Finally, run `yarn build` and give it a test run:
+
+```js
+bc@bifurcaria:~/streetcred/categories$ node
+Welcome to Node.js v12.6.0.
+Type ".help" for more information.
+> const cats = require('./dist/bundle')
+undefined
+> cats.findById(9001, 'io')
+{ id: 9001, name: 'Aero', icon: 'airport', attributes: undefined }
+>
+```
+
+### Maintaining translations
+
+The `translations` package script is a shortcut for extracting and compiling translations. It should be used after categories are added or modified, or if existing translations' `po`-files have been updated.
+
+## Local development and testing
+
 ### Clone the repo
@@ -133,3 +217,3 @@
 
-#### Run build once:
+### Run build once:
 
@@ -140,3 +224,3 @@ ```bash
 
-#### Generate translation files
+### Generate translation files
 
@@ -143,0 +227,0 @@ `yarn translations`

No alert changes

Improved metrics

Total package byte prevSize

393186

increased by0.8%

Number of package files

12

increased by9.09%

Lines of code

1598

increased by0.38%

Number of lines in readme file

235

increased by55.63%

No dependency changes