Update documentation an build

zakkudo · Sep 9, 2018 · 34940b1 · 34940b1
1 parent 32d739d
commit 34940b1
Show file tree

Hide file tree

Showing 16 changed files with 442 additions and 213 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -1,6 +1,8 @@
 language: node_js
 cache: yarn
 node_js:
+  - "6"
+#  - "7" NOT SUPPORTED BY fs-extra
   - "8"
   - "9"
   - "10"

diff --git a/README.md b/README.md
@@ -1,23 +1,14 @@
-<a name="module_TranslationStaticAnalyzer"></a>
+# @zakkudo/translation-static-analyzer
 
-## TranslationStaticAnalyzer
 A library for scanning javscript files to build translation mappings in json automatically.
 
-<p>
-<a href="https://travis-ci.org/zakkudo/translation-static-analyzer">
-    <img src="https://travis-ci.org/zakkudo/translation-static-analyzer.svg?branch=master"
-         alt="Build Status" /></a>
-<a href="https://coveralls.io/github/zakkudo/translation-static-analyzer?branch=master">
-    <img src="https://coveralls.io/repos/github/zakkudo/translation-static-analyzer/badge.svg?branch=master"
-         alt="Coverage Status" /></a>
-<a href="https://snyk.io/test/github/zakkudo/translation-static-analyzer">
-    <img src="https://snyk.io/test/github/zakkudo/translation-static-analyzer/badge.svg"
-         alt="Known Vulnerabilities"
-         data-canonical-src="https://snyk.io/test/github/zakkudo/translation-static-analyzer"
-         style="max-width:100%;" /></a>
-</p>
-
-Why use this?
+[![Build Status](https://travis-ci.org/zakkudo/translation-static-analyzer.svg?branch=master)](https://travis-ci.org/zakkudo/translation-static-analyzer)
+[![Coverage Status](https://coveralls.io/repos/github/zakkudo/translation-static-analyzer/badge.svg?branch=master)](https://coveralls.io/github/zakkudo/translation-static-analyzer?branch=master)
+[![Known Vulnerabilities](https://snyk.io/test/github/zakkudo/translation-static-analyzer/badge.svg)](https://snyk.io/test/github/zakkudo/translation-static-analyzer)
+[![Node](https://img.shields.io/node/v/@zakkudo/translation-static-analyzer.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why use this?
 
 - You no longer have to manage hierarchies of translations
 - Templates are automatically generated for the translators
@@ -26,78 +17,120 @@ Why use this?
 - Any string wrapped in `__()` or `__n()`, will be picked up as a
   translatable making usage extremely easy for developers
 
-What does it do?
+## What does it do?
 
 - I generates a locales directory filled with templates where the program was run, used by humans to translate
 - It generates .locale directories optimized for loading in each of the directories passed to targets
 - You load those translations from .locales as you need them
 
-Install with:
+## Install
 
 ```console
+# Install using npm
+npm install @zakkudo/translation-static-analyzer
+```
+
+``` console
+# Install using yarn
 yarn add @zakkudo/translation-static-analyzer
 ```
 
+## Setup
+1. Initialize the analyzer in your build scripts
+``` javascript
+const TranslationStaticAnalyzer = require('@zakkudo/translation-static-analyzer');
+const analyzer = new TransalationStaticAnalyzer({
+    // Analyzes all javscript files in the src directory, which is a good initial value
+    files: 'src/**/*.js',
+    // Use verbose output to see what files are parsed, what keys are extracted, and where they are being written to
+    debug: true,
+    // You do not need to add your default language (which for most people will be English)
+    locales: ['fr'],
+    // Consolidate all of the optimized localizations into `src/.locale`, good as an initial configuration
+    target: 'src'
+});
+```
+2. Use `analyzer.read(); analyzer.write();` to brute force updates to both translation templates and the final translations in the src directory. This avoids any checks for differences that try to minimize read/writes to the hard disk and makes it easier to get a working initial setup.
+3. Add `.locales` to your `.gitignore` so it isn't commited.  It is a dynamic source file that has no value being added to a repository. Its existance in the src directory is to facilitate importing it.
+4. Add `find src -name '.locales' | xargs rm -r` to your clean script assuming you want an easy way to clean out the auto generated locales
+5. Import locales into your source code from the `.locales` folder for use.  It is plain old json with untranslated and unexisting values optimized out.
+6. Have your localization team use the files from `locales` (without a period)  It's annoted with information about new, unused, and existing usages of the translations to help them audit what needs updating.
+``` javascript
+
+```
+
+## Also see
+
 Also consider `@zakkudo/translate-webpack-plugin` which is a wrapper for this library
 for webpack and `@zakkudo/translator` for a library that can read the localization with
-no fuss and apply the translations.  See the [Polymer 3 Starter Project](https://github.com/zakkudo/polymer-3-starter-project)
+no fuss and apply the translations.  See the
+[Polymer 3 Starter Project](https://github.com/zakkudo/polymer-3-starter-project)
 for an example of using this library.
 
-**Example** *(Usage for just translating everything in a project)*  
-```js
+## Examples
+
+### Usage for just translating everything in a project
+``` javascript
 const TranslationStaticAnalyzer = require('@zakkudo/translation-static-analyzer');
 const analyzer = new TransalationStaticAnalyzer({
-    files: 'src/**/*.js', // Analyzes all javscript files in the src directory
+    files: 'src/**\/*.js', // Analyzes all javscript files in the src directory
     debug: true, // Enables verbose output
     locales: ['fr', 'en'], // generate a locales/fr.json as well as a locales/en.json
     target: 'src' // Consolidate all of the localizations into src
 });
 analyzer.update();
 
+/*
 File Structure
-├── locales <- Your translators translate this
+├── locales <- Your translators translate this. It's json5 with comments
 │   ├── en.json
 │   └── fr.json
 └── src
-    ├── .locales <- Auto generated, should probably be added to .gitignore
+    ├── .locales <- Auto generated, you import from this, but make sure to add `.locales` to your `.gitignore`
     │   ├── en.json
     │   └── fr.json
     └── pages
         ├── About
         │   └── index.js
         └── Search
             └── index.js
+*/
 ```
-**Example** *(Usage for splitting transaltions between dynamically imported pages of a web app)*  
-```js
+
+### Usage for splitting translations between dynamically imported pages of a web app
+``` javascript
 const TranslationStaticAnalyzer = require('@zakkudo/translation-static-analyzer');
 const analyzer = new TransalationStaticAnalyzer({
-    files: 'src/**/*.js', // Analyzes all javscript files in the src directory
+    files: 'src/**\/*.js', // Analyzes all javscript files in the src directory
     debug: true, // Enables verbose output
     locales: ['fr', 'en'], // generate a locales/fr.json as well as a locales/en.json
     target: 'src/pages/*' // Each page in the folder will get it's own subset of translations
 });
 analyzer.update();
 
+/*
 File Structure
-├── locales <- Your translators translate this
+├── locales <- Your translators translate this. It's json5 with comments
 │   ├── en.json
 │   └── fr.json
 └── src
     └── pages
         ├── About
-        │   ├── .locales <- Auto generated, should probably be added to .gitignore
+        │   ├── .locales <- Auto generated, you import from this, but make sure to add `.locales` to your `.gitignore`
         │   │   ├── en.json
         │   │   └── fr.json
         │   └── index.js
         └── Search
-            ├── .locales <- Auto generated, should probably be added to .gitignore
+            ├── .locales <- Auto generated, you import from this, but make sure to add `.locales` to your `.gitignore`
+
             │   ├── en.json
             │   └── fr.json
             └── index.js
+*/
 ```
-**Example** *(Generated translation templates)*  
-```js
+
+### Generated translation templates
+``` javascript
 {
     // NEW
     // src/Application/pages/AboutPage/index.js:14
@@ -108,8 +141,9 @@ File Structure
     "Welcome to the about page!": "ようこそ"
 }
 ```
-**Example** *(Use the translations with @zakkudo/translator)*  
-```js
+
+### Use the translations with @zakkudo/translator
+``` javascript
 import Translator from '@zakkudo/translator';
 import localization = from './src/.locales/ja.json'; //Generated by the analyzer
 
@@ -121,29 +155,25 @@ const translated = translator.__('I love fish'); //Translate!
 const translated = translator.__n('There is a duck in the pond.', 'There are %d ducks in the pond', 3); //Translate!
 ```
 
-* [TranslationStaticAnalyzer](#module_TranslationStaticAnalyzer)
-    * [~TranslationStaticAnalyzer](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer)
-        * [new TranslationStaticAnalyzer(options)](#new_module_TranslationStaticAnalyzer..TranslationStaticAnalyzer_new)
-        * [.templateDirectory](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+templateDirectory) ⇒ <code>String</code>
-        * [.read([requestFiles])](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+read) ⇒ <code>Boolean</code>
-        * [.write()](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+write)
-        * [.update([requestFiles])](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+update)
+## API
+
+<a name="module_@zakkudo/translation-static-analyzer"></a>
 
-<a name="module_TranslationStaticAnalyzer..TranslationStaticAnalyzer"></a>
+<a name="module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer"></a>
 
-### TranslationStaticAnalyzer~TranslationStaticAnalyzer
+### @zakkudo/translation-static-analyzer~TranslationStaticAnalyzer ⏏
 Class description.
 
-**Kind**: inner class of [<code>TranslationStaticAnalyzer</code>](#module_TranslationStaticAnalyzer)  
+**Kind**: Exported class
 
-* [~TranslationStaticAnalyzer](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer)
-    * [new TranslationStaticAnalyzer(options)](#new_module_TranslationStaticAnalyzer..TranslationStaticAnalyzer_new)
-    * [.templateDirectory](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+templateDirectory) ⇒ <code>String</code>
-    * [.read([requestFiles])](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+read) ⇒ <code>Boolean</code>
-    * [.write()](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+write)
-    * [.update([requestFiles])](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+update)
+* [~TranslationStaticAnalyzer](#module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer)
+    * [new TranslationStaticAnalyzer(options)](#new_module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer_new)
+    * [.templateDirectory](#module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer+templateDirectory) ⇒ <code>String</code>
+    * [.read([requestFiles])](#module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer+read) ⇒ <code>Boolean</code>
+    * [.write()](#module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer+write)
+    * [.update([requestFiles])](#module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer+update)
 
-<a name="new_module_TranslationStaticAnalyzer..TranslationStaticAnalyzer_new"></a>
+<a name="new_module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer_new"></a>
 
 #### new TranslationStaticAnalyzer(options)
 
@@ -156,41 +186,41 @@ Class description.
 | [options.templates] | <code>String</code> |  | The location to store the translator translatable templates for each language |
 | [options.target] | <code>String</code> |  | Where to write the final translations, which can be split between multiple directories for modularity. |
 
-<a name="module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+templateDirectory"></a>
+<a name="module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer+templateDirectory"></a>
 
 #### translationStaticAnalyzer.templateDirectory ⇒ <code>String</code>
-**Kind**: instance property of [<code>TranslationStaticAnalyzer</code>](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer)  
+**Kind**: instance property of [<code>TranslationStaticAnalyzer</code>](#module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer)  
 **Returns**: <code>String</code> - The path to the directory which holds
 the translation templates that are dynamically updated
 by code changes and should be used by translators
 to add the localizations.  
-<a name="module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+read"></a>
+<a name="module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer+read"></a>
 
 #### translationStaticAnalyzer.read([requestFiles]) ⇒ <code>Boolean</code>
 Read changes from the source files and update the language templates.
 
-**Kind**: instance method of [<code>TranslationStaticAnalyzer</code>](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer)  
+**Kind**: instance method of [<code>TranslationStaticAnalyzer</code>](#module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer)  
 **Returns**: <code>Boolean</code> - True if some some of the modified files matches the
 file option passed on initialization  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
 | [requestFiles] | <code>Array.&lt;String&gt;</code> | <code>[]</code> | The files or none to update everything in the options.files glob pattern. |
 
-<a name="module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+write"></a>
+<a name="module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer+write"></a>
 
 #### translationStaticAnalyzer.write()
 Write to the targets. Use to force an update of the targets if a
 language file template in the templateDirectory is updated without
 updating a source file.
 
-**Kind**: instance method of [<code>TranslationStaticAnalyzer</code>](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer)  
-<a name="module_TranslationStaticAnalyzer..TranslationStaticAnalyzer+update"></a>
+**Kind**: instance method of [<code>TranslationStaticAnalyzer</code>](#module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer)  
+<a name="module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer+update"></a>
 
 #### translationStaticAnalyzer.update([requestFiles])
 Updates the translations to match the source files.
 
-**Kind**: instance method of [<code>TranslationStaticAnalyzer</code>](#module_TranslationStaticAnalyzer..TranslationStaticAnalyzer)  
+**Kind**: instance method of [<code>TranslationStaticAnalyzer</code>](#module_@zakkudo/translation-static-analyzer..TranslationStaticAnalyzer)  
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |

diff --git a/package.json b/package.json
@@ -15,25 +15,30 @@
     "files": [
         "*"
     ],
+    "engines": {
+        "node": ">=6.0.0 <7.0.0 || >=8.0.0"
+    },
     "repository": "github:zakkudo/translation-static-analyzer",
     "license": "BSD-3-Clause",
     "devDependencies": {
         "@babel/cli": "^7.0.0-beta.56",
         "@babel/core": "^7.0.0-beta.56",
+        "@babel/plugin-transform-runtime": "^7.0.0",
         "@babel/preset-env": "^7.0.0-beta.56",
         "babel-core": "^7.0.0-0",
         "babel-jest": "^23.4.2",
+        "babel-plugin-transform-undefined-to-void": "^6.9.4",
         "eslint": "^4.19.1",
         "eslint-plugin-jasmine": "^2.10.1",
         "eslint-plugin-jest": "^21.21.0",
         "eslint-plugin-node": "^7.0.1",
         "jest": "^23.4.2",
         "jest-cli": "^23.4.2",
         "jsdoc": "^3.5.5",
-        "jsdoc-to-markdown": "^4.0.1",
-        "regenerator-runtime": "^0.12.1"
+        "jsdoc-to-markdown": "^4.0.1"
     },
     "dependencies": {
+        "@babel/runtime-corejs2": "^7.0.0",
         "deep-equal": "^1.0.1",
         "fs-extra": "^7.0.0",
         "glob": "^7.1.2",
@@ -49,8 +54,5 @@
         "lint": "scripts/lint.sh",
         "deploy": "scripts/deploy.sh",
         "test": "scripts/test.sh"
-    },
-    "engines": {
-        "node": ">=8.0.0"
     }
 }
diff --git a/scripts/build.sh b/scripts/build.sh
@@ -2,4 +2,25 @@
 
 set -e
 
-./node_modules/.bin/babel src --out-dir build --source-maps inline --ignore "src/*.test.js" --ignore "src/test.js"
+export NODE_ENV="build"
+
+CURRENT_DIR=$(pwd)
+PROJECT_DIR=$(git rev-parse --show-toplevel)
+
+cd $PROJECT_DIR
+
+./scripts/clean.sh
+./scripts/document.sh
+
+mkdir build
+
+cp package.json build/package.json
+cp README.md build/README.md
+
+./node_modules/.bin/babel src \
+    --out-dir build \
+    --source-maps inline \
+    --ignore "src/test.js" \
+    --ignore "src/*.test.js" \
+    --verbose \
+    "$@"
diff --git a/scripts/clean.sh b/scripts/clean.sh
@@ -2,15 +2,13 @@
 
 set -e
 
+CURRENT_DIR=$(pwd)
 PROJECT_DIR=$(git rev-parse --show-toplevel)
-BIN_DIR=$(npm bin)
-JSDOC="$BIN_DIR/jsdoc"
 
-rm -rf $PROJECT_DIR/build
-rm -rf $PROJECT_DIR/coverage
-rm -rf $PROJECT_DIR/documentation
-rm -rf $PROJECT_DIR/demo
-rm -f $PROJECT_DIR/.karma-test-results.json
-rm -f $PROJECT_DIR/.jest-test-results.json
-rm -f $PROJECT_DIR/jsdoc.*.conf.tmp
-rm -f $PROJECT_DIR/yarn-error.log
+cd $PROJECT_DIR
+
+rm -rf build
+rm -rf coverage
+rm -rf documentation
+rm -f jsdoc.*.conf.tmp
+rm -f yarn-error.log
diff --git a/scripts/cover.sh b/scripts/cover.sh
@@ -1,3 +1,11 @@
-#!/bin/sh
+#!/bin/bash
 
-./node_modules/.bin/jest --coverage --config jest.config.js
+set -e
+
+CURRENT_DIR=$(pwd)
+PROJECT_DIR=$(git rev-parse --show-toplevel)
+
+cd $PROJECT_DIR
+
+./scripts/clean.sh
+./scripts/test.sh --coverage --coveragePathIgnorePatterns '.*TestHelper.js' "$@"