@vocab/types - npm Package Compare versions

Comparing version 0.0.3 to 0.0.4

CHANGELOG.md

 # @vocab/types
 
+## 0.0.4
+
+### Patch Changes
+
+- [`08de30d`](https://github.com/seek-oss/vocab/commit/08de30d338c2a5ebdcf14da7c736dddf22e7ca9e) [#14](https://github.com/seek-oss/vocab/pull/14) Thanks [@mattcompiles](https://github.com/mattcompiles)! - Add ability to override files namespace with \$namespace
+
 ## 0.0.3
@@ -4,0 +10,0 @@

dist/declarations/src/index.d.ts

@@ -11,5 +11,3 @@ import type { IntlMessageFormat } from 'intl-messageformat';
 export interface RawJsonTranslations {
-    [translationKey: string]: {
-        message: string;
-    };
+    [translationKey: string]: string;
 }
@@ -33,10 +31,12 @@ export interface LanguageTarget {
 export declare type LanguageName = string;
-export declare type TranslationsByLanguage = Record<string, {
+export declare type TranslationsByLanguage<Key extends string = string> = Record<Key, {
     message: string;
     description?: string;
 }>;
-export declare type LoadedTranslation = {
+export declare type LoadedTranslation<Key extends string = string> = {
+    namespace: string;
+    keys: Array<Key>;
     filePath: string;
     relativePath: string;
-    languages: Map<LanguageName, TranslationsByLanguage>;
+    languages: Map<LanguageName, TranslationsByLanguage<Key>>;
 };

package.json

 {
   "name": "@vocab/types",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "main": "dist/vocab-types.cjs.js",
@@ -5,0 +5,0 @@ "module": "dist/vocab-types.esm.js",

README.md

 # Vocab
 
-Vocab is a strongly-typed internationalisation framework for React
+Vocab is a strongly typed internationalisation framework for React.
+
+## Getting started
+
+### Step 1: Install Dependencies
+
+Vocab is a monorepo with different packages you can install depending on your usage, the below list will get you started using the cli, React and webpack integrations.
+
+```bash
+$ npm i --save @vocab/cli @vocab/react @vocab/webpack
+```
+
+### Step 2: Setup Webpack plugin
+
+Before starting to write code you'll need to setup webpack to understand how to use `translation.json` files.
+
+This is done using the **VocabWebpackPlugin**.
+
+**webpack.config.js**
+
+```js
+const VocabWebpackPlugin = require('@vocab/webpack').default;
+
+module.exports = {
+  ...,
+  plugins: [new VocabWebpackPlugin({})]
+}
+```
+
+### Step 3: Configure Vocab
+
+You can configure Vocab directly when calling the API or via a `vocab.config.js` file.
+
+In this example we've configured two languages, English and French, where our initial `translation.json` files will use English.
+
+**vocab.config.js**
+
+```js
+module.exports = {
+  devLanguage: 'en',
+  languages: [{ name: 'en' }, { name: 'fr' }]
+};
+```
+
+### Step 3: Set the language using the React Provider
+
+Vocab doesn't tell you how to select or change your language. You just need to tell Vocab what language to use.
+
+**Note:** Using methods discussed later we'll make sure the first language is loaded on page load. However, after this changing languages may then lead to a period of no translations as Vocab downloads the new language's translations.
+
+**src/App.tsx**
+
+```tsx
+import { TranslationsProvider } from '@vocab/react';
+
+function App({ children }) {
+  return (
+    <TranslationsProvider language={language}>
+      {children}
+    </TranslationsProvider>
+  );
+}
+```
+
+### Step 4: Create initial values and use them
+
+A translation file is a JSON file consisting of a flat structure of keys, each with a message and an optional description.
+
+**./translations.json**
+
+```json
+{
+  "my key": {
+    "message": "Hello from Vocab",
+    "description": "An optional description to help when translating"
+  }
+}
+```
+
+You can then import these translations into your React components. Translations can be used by calling the `t` function returned by `useTranslation`.
+
+**./MyComponent.tsx**
+
+```tsx
+import { useTranslation } from '@vocab/react';
+import translations from './translations.json';
+
+function MyComponent({ children }) {
+  const { t } = useTranslation(translations);
+  return <div>{t('my key')}</div>;
+}
+```
+
+### Step 5: Create translations
+
+So far your app will run, but you're missing any translations other than the initial language. The below file can be created manually; however, you can also integrate with a remote translation platform to push and pull translations automatically.
+
+**./\_\_translations\_\_/translations.fr-FR.json**
+
+```json
+{
+  "my key": {
+    "message": "Bonjour de Vocab",
+    "decription": "An optional description to help when translating"
+  }
+}
+```
+
+### Step 6: Optimize for fast page loading
+
+Using the above method without optimizing what chunks webpack uses you may find the page needing to do an extra round trip to load languages on a page.
+
+This is where `getChunkName` can be used to retrieve the Webpack chunk used for a specific language.
+
+For example here is a Server Render function that would add the current language chunk to [Loadable component's ChunkExtractor](https://loadable-components.com/docs/api-loadable-server/#chunkextractor).
+
+**src/render.tsx**
+
+```tsx
+import { getChunkName } from '@vocab/webpack/chunk-name';
+
+// ...
+
+const chunkName = getChunkName(language);
+
+const extractor = new ChunkExtractor();
+
+extractor.addChunk(chunkName);
+```
+
+## Configuration
+
+Configuration can either be passed into the Node API directly or be gathered from the nearest _vocab.config.js_ file.
+
+**vocab.config.js**
+
+```js
+module.exports = {
+  devLanguage: 'en',
+  languages: [
+    { name: 'en' },
+    { name: 'en-AU', extends: 'en' },
+    { name: 'en-US', extends: 'en' },
+    { name: 'fr-FR' }
+  ]
+};
+```
+
+## Generate Types
+
+Vocab generates custom `translation.json.d.ts` files that give your React components strongly typed translations to work with.
+
+To generate these types run:
+
+```bash
+$ vocab generate-types
+```
+
+## External translation tooling
+
+Vocab can be used to syncronize your translations with translations from a remote translation platform.
+
+| Platform                                     | Environment Variables               |
+| -------------------------------------------- | ----------------------------------- |
+| [Phrase](https://developers.phrase.com/api/) | PHRASE_PROJECT_ID, PHRASE_API_TOKEN |
+
+```bash
+$ vocab push --branch my-branch
+$ vocab pull --branch my-branch
+```
+
+### License
+
+MIT.

src/index.ts

@@ -18,5 +18,3 @@ import type { IntlMessageFormat } from 'intl-messageformat';
 export interface RawJsonTranslations {
-  [translationKey: string]: {
-    message: string;
-  };
+  [translationKey: string]: string;
 }
@@ -46,4 +44,4 @@
 
-export type TranslationsByLanguage = Record<
-  string,
+export type TranslationsByLanguage<Key extends string = string> = Record<
+  Key,
   {
@@ -55,6 +53,8 @@ message: string;
 
-export type LoadedTranslation = {
+export type LoadedTranslation<Key extends string = string> = {
+  namespace: string;
+  keys: Array<Key>;
   filePath: string;
   relativePath: string;
-  languages: Map<LanguageName, TranslationsByLanguage>;
+  languages: Map<LanguageName, TranslationsByLanguage<Key>>;
 };

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

8732

increased by139.17%

Number of lines in readme file

177

increased by4325%

No dependency changes