feat: load translation resources automatically + add example website

udpate README.md
yassinedoghri · May 12, 2022 · 48dd98e · 48dd98e
1 parent 70c25f0
commit 48dd98e
Show file tree

Hide file tree

Showing 20 changed files with 11,576 additions and 26 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -17,10 +17,12 @@
   // Add the IDs of extensions you want installed when the container is created.
   "extensions": [
     "astro-build.astro-vscode",
+    "bradlc.vscode-tailwindcss",
     "DavidAnson.vscode-markdownlint",
     "dbaeumer.vscode-eslint",
     "eamodio.gitlens",
     "esbenp.prettier-vscode",
+    "heybourn.headwind",
     "pflannery.vscode-versionlens",
     "streetsidesoftware.code-spell-checker",
     "wayou.vscode-todo-highlight",

diff --git a/README.md b/README.md
@@ -1,71 +1,178 @@
-# 🚀 Astro i18next 🌍
+# 🧪 astro-i18next
 
-i18next components to help translate [astro](https://astro.build/) websites.
+An [astro](https://astro.build/) integration of
+[i18next](https://www.i18next.com/) + some
+[utility components](#utility-components) to help you translate your astro
+websites!
 
 > **Status** [alpha version]
 >
-> Currently in development, not ready yet! Missing tests, better integration,
-> better docs and examples
+> Currently in development, can be used though some breaking changes may be
+> introduced from a version to another!
 
-## Install
+## Getting started
+
+### 1. Install
 
 ```bash
 npm install astro-i18next
 ```
 
-```bash
-pnpm add astro-i18next
+## 2. Configure
+
+1. Add `astro-i18next` to your `astro.config.mjs`:
+
+   ```mjs
+   import { defineConfig } from "astro/config";
+   import astroI18next from "astro-i18next";
+
+   export default defineConfig({
+     experimental: {
+       integrations: true,
+     },
+     integrations: [
+       astroI18next({
+         resourcesPath: "./src/locales/",
+         i18nextConfig: {
+           debug: true,
+           fallbackLng: ["en", "fr"],
+           supportedLngs: ["en", "fr"],
+         },
+       }),
+     ],
+   });
+   ```
+
+2. Create a `locales` folder containing the translation strings as JSONs:
+
+   ```bash
+   src
+   ├-- locales          # astro-i18next will load all supported locales
+   |   |-- en.json      # english translation strings
+   |   └-- fr.json      # french translation strings
+   └-- pages
+       |-- [lang].astro # you may add a dynamic route to generate language routes
+       └-- index.astro  # route for base language (first element in fallbackLng)
+   ```
+
+## 3. Translate!
+
+You're all set! You may now start translating your website by using
+[i18next's `t` function](https://www.i18next.com/overview/api#t) or the
+[Trans component](#trans-component) depending on your needs.
+
+Here's a quick tutorial:
+
+```astro
+---
+// src/pages/index.astro
+import i18next, { t } from "i18next";
+
+// You may change language
+i18next.changeLanguage("fr");
+---
+
+<html lang={i18next.language}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width" />
+    <title>{t("site.title")}</title>
+    <meta name="description" content={t("site.description")} />
+  </head>
+  <body>
+    <h1>{t("home.title")}</h1>
+    <p>
+      <Trans i18nKey="home.subtitle">
+        This is a <em>more complex</em> string to translate, mixed with <strong
+          >html elements
+        </strong> such as a <a href="https://example.com/">a cool link</a>!
+      </Trans>
+    </p>
+  </body>
+</html>
 ```
 
-```bash
-yarn add astro-i18next
+```json
+// src/locales/en.json
+{
+  "site": {
+    "title": "My awesome website!",
+    "description": "Here is the description of my awesome website!"
+  },
+  "home": {
+    "title": "Welcome to my awesome website!",
+    "subtitle": "This is a <0>more complex</0> string to translate, mixed with <1>html elements</1>, such as a <2>a link</2>!"
+  }
+}
 ```
 
-## Usage
+```json
+// src/locales/fr.json
+{
+  "site": {
+    "title": "Mon super site web !",
+    "description": "Voici la description de mon super site web !"
+  },
+  "home": {
+    "title": "Bienvenue sur mon super site web !",
+    "subtitle": "Ceci est une chaine de charactères <0>plus compliquée</0> à traduire, il y a des <1>éléments html</1>, comme <2>un lien</2> par exemple !"
+  }
+}
+```
+
+For a more exhaustive example, see the [example astro website](./example/).
+
+## Utility components
 
 ### Trans component
 
+A component that takes care of interpolating its children with the translation
+strings. Inspired by
+[react-i18next's Trans component](https://react.i18next.com/latest/trans-component).
+
 ```astro
 ---
-import { Trans } from "astro-i18next";
+import { Trans } from "astro-i18next/components";
 ---
 
-<Trans i18nKey="superCoolKey">
-  This is a <strong>super cool</strong> sentence!
+<Trans i18nKey="sampleKey">
+  An <a href="https://astro.build" title="Astro website">astro</a> integration of
+  <a href="https://www.i18next.com/" title="i18next website">i18next</a> and utility
+  components to help you translate your astro websites!
 </Trans>
 ```
 
 ```json
 // fr.json
 {
-  "superCoolKey": "Ceci est une phrase <0>super cool</0>!"
+  "superCoolKey": "Une intégration <0>astro</0> d'<1>i18next</1> + quelques composants utilitaires pour vous aider à traduire vos sites astro !"
 }
 ```
 
 #### Trans Props
 
-| Propname | Type   | Description              |
-| -------- | ------ | ------------------------ |
-| i18nKey  | string | Internationalization key |
+| Prop name | Type   | Description                                |
+| --------- | ------ | ------------------------------------------ |
+| i18nKey   | string | Internationalization key to interpolate to |
 
 ### LanguageSelector component
 
 Unstyled custom select component to choose amongst supported locales.
 
 ```astro
 ---
-import { LanguageSelector } from "astro-i18next";
+import { LanguageSelector } from "astro-i18next/components";
 ---
 
 <LanguageSelector className="my-select-class" />
 ```
 
 #### LanguageSelector Props
 
-| Propname     | Type   | Description                                                                                           |
-| ------------ | ------ | ----------------------------------------------------------------------------------------------------- |
-| baseLanguage | string | language code that translations are based off of (will redirect to `/` instead of `/[language-code]`) |
-| className    | string | class attribute for the `<select>` tag to customize it                                                |
+| Prop name    | Type    | Description                                                                                           |
+| ------------ | ------- | ----------------------------------------------------------------------------------------------------- |
+| baseLanguage | string  | language code that translations are based off of (will redirect to `/` instead of `/[language-code]`) |
+| className    | ?string | class attribute for the `<select>` tag to customize it                                                |
 
 ## License
 

diff --git a/example/.gitignore b/example/.gitignore
@@ -0,0 +1,20 @@
+# build output
+dist/
+.output/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
diff --git a/example/.npmrc b/example/.npmrc
@@ -0,0 +1,2 @@
+# Expose Astro dependencies for `pnpm` users
+shamefully-hoist=true
diff --git a/example/.vscode/extensions.json b/example/.vscode/extensions.json
@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}
diff --git a/example/.vscode/launch.json b/example/.vscode/launch.json
@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}
diff --git a/example/README.md b/example/README.md
@@ -0,0 +1,46 @@
+# Astro Starter Kit: Minimal
+
+```
+npm init astro -- --template minimal
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/astro/tree/latest/examples/minimal)
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro project, you'll see the following folders and files:
+
+```
+/
+├── public/
+├── src/
+│   └── pages/
+│       └── index.astro
+└── package.json
+```
+
+Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page
+is exposed as a route based on its file name.
+
+There's nothing special about `src/components/`, but that's where we like to put
+any Astro/React/Vue/Svelte/Preact components.
+
+Any static assets, like images, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command           | Action                                       |
+| :---------------- | :------------------------------------------- |
+| `npm install`     | Installs dependencies                        |
+| `npm run dev`     | Starts local dev server at `localhost:3000`  |
+| `npm run build`   | Build your production site to `./dist/`      |
+| `npm run preview` | Preview your build locally, before deploying |
+
+## 👀 Want to learn more?
+
+Feel free to check [our documentation](https://github.com/withastro/astro) or
+jump into our [Discord server](https://astro.build/chat).
diff --git a/example/astro.config.mjs b/example/astro.config.mjs
@@ -0,0 +1,21 @@
+import { defineConfig } from "astro/config";
+import tailwind from "@astrojs/tailwind";
+import astroI18next from "astro-i18next";
+
+// https://astro.build/config
+export default defineConfig({
+  experimental: {
+    integrations: true,
+  },
+  integrations: [
+    tailwind(),
+    astroI18next({
+      resourcesPath: "./src/locales/",
+      i18nextConfig: {
+        debug: true,
+        fallbackLng: ["en", "fr"],
+        supportedLngs: ["en", "fr"],
+      },
+    }),
+  ],
+});
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# Expose Astro dependencies for `pnpm` users
		shamefully-hoist=true