@nkzw/eslint-plugin-fbtee 1.2.2 → 1.2.6

package/README.md

@@ -2,17 +2,25 @@
 
 _**fbtee** (Far Better Translations, Extended Edition) is an internationalization framework for JavaScript & React designed to be **powerful**, **flexible**, and **intuitive**._
 
-## Why `fbtee`?
+fbtee features inline translations and supports dynamic content, pluralization, lists, and more. It is built on top of Facebook's `fbt` library, which has been used in production for over a decade, serving billions of users.
+
+```tsx
+const Greeting = ({ name }) => (
+  <div>
+    <fbt desc="Greeting">
+      Hello, <Name name={name} />!
+    </fbt>
+  </div>
+);
+```
+
+## Why choose **fbtee**?
 
 - **Inline translations for Better Developer Experience:** Embed translations directly into your code. No need to manage translation keys or wrap your code with `t()` functions. **fbtee** uses a compiler to extract strings from your code and prepare them for translation providers.
 - **Proven in Production:** Built on Facebook's `fbt`, with over a decade of production usage, serving billions of users and two years of production usage in [Athena Crisis](https://athenacrisis.com).
 - **Optimized Performance with IR:** Compiles translations into an Intermediate Representation (IR) for extracting strings, then optimizes the runtime output for performance.
 - **Easy Setup:** Quick integration with tools like Babel and Vite means you can get started instantly.
 
-## Status: Ready for Early Adopters
-
-This is a fork of Facebook's original `fbt` library, which has been archived. The aim of this fork is to create the best and most modern internationalization library for JavaScript & React.
-
 ## Getting Started
 
 Tired of setting up new projects? Check out these templates for web and React Native that come with **fbtee** pre-configured:
@@ -20,6 +28,13 @@ Tired of setting up new projects? Check out these templates for web and React Na
 - [Web App Template](https://github.com/nkzw-tech/web-app-template)
 - [Expo App Template](https://github.com/nkzw-tech/expo-app-template)
 
+### Examples
+
+Sometimes it's easiest to learn by example and copy-paste the setup from existing projects. Here are some examples of using **fbtee**:
+
+- [Next.js App fbtee Example](https://github.com/cpojer/nextjs-fbtee-example) - A Next.js App Router example using **fbtee** with Server Components.
+- [Athena Crisis](https://github.com/nkzw-tech/athena-crisis) - an open source video game using **fbtee**
+
 ### Installation
 
 **fbtee** requires at least Node 22, and React 19 if you are using React.
@@ -28,14 +43,20 @@ Tired of setting up new projects? Check out these templates for web and React Na
 npm install fbtee
 ```
 
-In addition to `fbtee`, you need to install the Babel preset and React plugin for Vite:
+In addition to `fbtee`, you need to install the Babel preset.
 
 ```bash
-npm install -D @nkzw/babel-preset-fbtee @vitejs/plugin-react
+npm install -D @nkzw/babel-preset-fbtee
 ```
 
 ### Tooling Setup
 
+If you are using Vite, install the React plugin for Vite:
+
+```bash
+npm install -D @vitejs/plugin-react
+```
+
 In your `vite.config.ts`:
 
 ```ts
@@ -55,7 +76,7 @@ export default {
 
 #### Using Babel directly instead of Vite's React Plugin
 
-If you are not using `@vitejs/plugin-react`, for example because you are using the latest version of React Router in framework mode, you can use `vite-plugin-babel` instead:
+If you are not using `@vitejs/plugin-react`, for example, because you are using the latest version of React Router in framework mode, you can use `vite-plugin-babel` instead:
 
 ```tsx
 import fbteePreset from '@nkzw/babel-preset-fbtee';
@@ -73,6 +94,16 @@ export default defineConfig({
 });
 ```
 
+#### Using **fbtee** with Next.js
+
+Create a `babel.config.js` file in the root of your Next.js project and add the **fbtee** preset:
+
+```tsx
+export default {
+  presets: ['next/babel', '@nkzw/babel-preset-fbtee'],
+};
+```
+
 #### Scripts
 
 **fbtee** uses two scripts to manage translations. These scripts help automate the process of collecting, creating, and compiling translations.
@@ -102,7 +133,7 @@ Now, run the collect command to set up the initial strings for translation:
 pnpm fbtee collect
 ```
 
-The files generated by these commands should be added to `.gitignore`:
+Add the files generated by these commands to your `.gitignore`:
 
 ```
 .enum_manifest.json
@@ -110,14 +141,14 @@ source_strings.json
 src/translations/
 ```
 
-Since you won't have any translations yet, we need to create an empty translations file. Just run this command to create the empty file:
+Because no translations exist yet, you can run this command to create an empty file for now:
 
 ```bash
 mkdir -p translations
 echo '{"fb-locale": "ja_JP", "translations": {}}' > translations/ja_JP.json
 ```
 
-If you are not using a translation provider, you can also run `fbtee prepare-translations --locale ja_JP` to generate a JSON file that can be edited directly.
+If you are not using a translation provider, you can also run `fbtee prepare-translations --locales ja_JP` to generate a JSON file that can be edited directly.
 
 ### App Setup
 
@@ -148,7 +179,7 @@ const loadLocale = async (locale: string) => {
 };
 
 const LocaleContext = createLocaleContext({
-  availableLangauges,
+  availableLanguages,
   clientLocales: clientLocalesWeb, // or clientLocalesRN for React Native
   loadLocale,
 });
@@ -208,6 +239,41 @@ if (getLocale() === 'en_US') {
 
 A full example of using `setupLocaleContext` to build your own `LocaleContext` abstraction can be found in the [Athena Crisis](https://github.com/nkzw-tech/athena-crisis/blob/main/hera/i18n/LocaleContext.tsx#L41) repository.
 
+### Gender Variations
+
+`createLocaleContext` and `setupLocaleContext` also support setting the user's gender:
+
+```tsx
+createLocaleContext({
+  …
+  gender: 'female', // 'male', 'female' or 'unknown' are supported.
+});
+```
+
+If you need to adjust the user's gender dynamically, you can use the `setGender` function provided by the `useLocaleContext` hook:
+
+```tsx
+import { useLocaleContext } from 'fbtee';
+
+const GenderSelector = () => {
+  const { gender, setGender } = useLocaleContext();
+
+  return (
+    <div>
+      <button onClick={() => setGender('male')}>
+        <fbt desc="Male gender">Male</fbt>
+      </button>
+      <button onClick={() => setGender('female')}>
+        <fbt desc="Female gender">Female</fbt>
+      </button>
+      <button onClick={() => setGender('unknown')}>
+        <fbt desc="Unknown gender">Unknown</fbt>
+      </button>
+    </div>
+  );
+};
+```
+
 #### Full Customization
 
 Finally, if you are using something other than React, or need even more control over how **fbtee** is configured, you can use the `setupFbtee` function. This function allows you to set up **fbtee** with custom hooks and translations:
@@ -227,11 +293,19 @@ setupFbtee({
 });
 ```
 
+### Usage with Next.js
+
+If you are using Next.js with App Router, check out the [Next.js App fbtee Example](https://github.com/cpojer/nextjs-fbtee-example). You'll need to set up a `<LocaleContext />` as a Client Component, and call `setupFbtee` in the root layout of your app for Server Component support.
+
+When using Next.js with **fbtee**, translated strings are inserted when your Server Components are rendered. This means that changing locales on the client will not automatically update the Server Component's translated strings. To handle locale changes, you need to call a server action that updates the locale, and then re-render your app with the new locale, for example by reloading the page.
+
+If you are exclusively using **fbtee** within Client Components, you can handle locale changes directly on the client only.
+
 ## Usage
 
 _If you want to learn by example, check out the [examples](https://github.com/nkzw-tech/fbtee/tree/main/example) directory. You can also check out [Athena Crisis](https://github.com/nkzw-tech/athena-crisis), a large open source video game using **fbtee**_
 
-With **fbtee**, all strings need to be wrapped using `<fbt>` (for React/JSX) or `fbt()` (for JavaScript). This ensures strings can be extracted and translated properly. The `desc` attribute is required and provides context for translators, helping them understand the intended meaning of the string.
+With **fbtee**, all strings must be wrapped using `<fbt>` (for React/JSX) or `fbt()` (for JavaScript). This ensures strings can be extracted and translated properly. The `desc` attribute is required and provides context for translators, helping them understand the intended meaning of the string.
 
 Here are some basic examples:
 
@@ -249,7 +323,39 @@ const Greeting = () => (
 );
 ```
 
-`<fbt>` is a special React component that marks text for translation. The `fbtee` compiler analyzes them to extract strings, and compiles them into an Intermediate Representation (IR). It supports dynamic content through <fbt:param> or even other React components. For example, if you want to greet a specific user based on a name passed as a prop, you can use `<fbt:param>`:
+`<fbt>` is a special React component that marks text for translation. The **fbtee** compiler analyzes them to extract strings, and compiles them into an Intermediate Representation (IR). Here is a more complex example of what you can do with **fbtee**:
+
+```tsx
+<fbt desc="Feed item">
+  <fbt:list items={users} name="userList" />{' '}
+  <fbt:plural
+    count={users.length}
+    many="are"
+    name="number of players"
+    showCount="no"
+  >
+    is
+  </fbt:plural>{' '}
+  playing on
+  <fbt:param name="mapName">{game.mapName}</fbt:param>
+</fbt>
+```
+
+_Note: `<fbt>` is auto-imported for you by the `@nkzw/babel-preset-fbtee` plugin._
+
+This example highlights several features of **fbtee**:
+
+- `<fbt:list>`: Renders a list of items, automatically handling conjunctions and delimiters.
+- `<fbt:plural>`: Handles singular and plural forms based on a count value.
+- `<fbt:param>`: Allows you to insert dynamic content into your strings, such as variables or React components.
+
+With the above components, you can handle complex strings that are translatable into multiple languages while maintaining clarity and context for translators. This sentence structure supports many variations, such as "Alice is playing on Forest Battle.", or "Alice, Bob and Charlie are playing on Giant Crisis".
+
+Let's look at each of these features in detail:
+
+### Dynamic Content
+
+**fbtee** supports dynamic content through <fbt:param> or by using other React components within your text. For example, if you want to greet a specific user based on a name passed as a prop, you can use `<fbt:param>`:
 
 ```tsx
 const Greeting = ({ name }) => (
@@ -273,7 +379,74 @@ const Greeting = ({ name }) => (
 );
 ```
 
-_Note: `<fbt>` is auto-imported for you by the `@nkzw/babel-preset-fbtee` plugin._
+### Lists
+
+`<fbt:list>` is used to render a list of items with conjunctions and delimiters. It automatically handles the grammatical structure of the list based on the locale:
+
+```tsx
+<fbt:list
+  conjunction="or"
+  delimiter="comma"
+  items={['Alice', 'Bob', <CharlieNameExampleComponent key="charlieUserID" />]}
+  name="userList"
+/> // "Alice, Bob, or Charlie"
+```
+
+The default conjunction is "and", and the default delimiter is "comma". You can use "or" or "none" as conjunction, and "bullet", "comma", or "semicolon" as delimiters. The `name` attribute is required to provide context for translators. **fbtee** also exports a `list` function that can be used in contexts outside of React:
+
+```tsx
+import { list } from 'fbtee';
+
+const userList = list(['Alice', 'Bob', 'Charlie'], 'or', 'comma');
+```
+
+### Singular & Plural Forms
+
+**fbtee** supports singular and plural forms using the `<fbt:plural>` component. While in English, the plural form is often just an "s" at the end of a word, in other languages, it can be more complex. **fbtee** handles this automatically based on the count value you provide. Here's an example:
+
+```tsx
+<fbt desc="end turn confirmation">
+  Do you want to play against
+  <fbt:plural count={bots} many="bots" name="numberOfBots" showCount="ifMany">
+    a bot
+  </fbt:plural>?
+</fbt>
+```
+
+This sentence might be translated to one of the following variations:
+
+- "Do you want to play against 1 bot?"
+- "Do you want to play against 2 bots?"
+
+`<fbt:plural>` expects the singular phrase as children, and an item `count` as prop. You can provide the plural form using the `many` prop. The `showCount` prop can be used to control whether the count should be displayed in the string. `ifMany` only shows the count in the plural case, while `yes` shows it in all cases, and `no` hides it completely. The `name` prop is required to provide context for translators.
+
+### Using Pronouns
+
+You can use `<fbt:pronoun>` to handle pronouns in your strings. This is particularly useful for gendered languages where the pronoun changes based on the subject:
+
+```tsx
+<fbt desc="Photo sharing text">
+  <fbt:param name="name">{user.name}</fbt:param>
+  shared
+  <fbt:pronoun type="possessive" gender={user.pronounGender} human />
+  photo with you.
+</fbt>
+```
+
+### Plain Text Usage
+
+In some situations, you may want to use **fbtee** to represent plain text strings without any React components, for example when using alert dialogs or HTML attributes like `placeholder`. For these situations, you can use the `fbs()` function, which is a subset of `fbt` that only supports plain text.
+
+```tsx
+import { fbs } from 'fbtee';
+
+<input
+  type="text"
+  placeholder={fbs('Enter your name', 'Placeholder for name input')}
+/>;
+```
+
+### Extracting Strings & Translating
 
 After marking your strings for translation with `<fbt>`, run the following commands to extract, and compile translations:
 
@@ -281,9 +454,9 @@ After marking your strings for translation with `<fbt>`, run the following comma
 pnpm fbtee collect
 ```
 
-You can now upload the `source_strings.json` file to your translation provider. One sample for such a translation provider is [Crowdin](https://crowdin.com/).
+You can now upload the `source_strings.json` file to your translation provider, for example [Crowdin](https://crowdin.com/). If you'd like to manually edit the strings, you can use the `fbtee prepare-translations --locales de_DE` to generate a JSON file that can be edited directly.
 
-### Generated File Structure
+#### Generated File Structure
 
 Your `source_strings.json` might look like this:
 
@@ -356,24 +529,79 @@ And German (`translations/de_DE.json`) might look like this:
 }
 ```
 
-Once you have the translated strings stored in a `translations/` folder as JSON files, you can run the following command to generate the translations file:
+Once you have the translated strings stored in a `translations/` folder as JSON files using the locale name, for example `en_US.json` or `de_DE.json`, you can run the following command to generate the translations for use in your app:
 
 ```bash
 pnpm fbtee translate
 ```
 
-This will generate the `translation.json` file referred to in the setup done before. This file might look like this:
+By default, **fbtee** outputs the generated translations in `src/translations`. It will create one JSON file per locale. For example, if you have `translations/en_US.json` and `translations/de_DE.json`, it will generate `src/translations/en_US.json` and `src/translations/de_DE.json`. These files are an optimized representation of your translation file, ready to be used in your app:
 
 ```json
 {
-  "de_DE": { "2HVYhv": "Was kommt jetzt?" },
-  "en_US": { "2HVYhv": "What's next?" }
+  "de_DE": {
+    "2HVYhv": "Was kommt jetzt?"
+  }
 }
 ```
 
-After generating the translations file, your app is ready to display translated content in other languages. The error you had until now in the `setupFbtee` with regards to the imported translations file should be resolved now.
+After generating the translation files, your app is ready to display translated content in other languages. Since the `src/translations` folder is auto-generated, it should be ignored by version control and be part of your build process.
 
-Since the `translations.json` is an auto-generated file part of your build process, the `fbtee translate` command should be added to your build step.
+## Setting the initial locale
+
+If you know the user's locale ahead of time, you can set it when creating the `LocaleContext` by passing the locale as the first item in the `clientLocales` array:
+
+```tsx
+// Read the user locale from localStorage etc.
+const userLocale = localStorage.getItem('locale');
+const LocaleContext = createLocaleContext({
+  availableLanguages,
+  clientLocales: [userLocale, navigator.language, ...navigator.languages],
+  loadLocale,
+});
+```
+
+Note that if you are picking the locale ahead of time like this, you need to manually load the translations. This is because the `loadLocale` function is only called when the locale changes, and not when the context is first created. This gives you full control over your app's startup:
+
+```tsx
+const loadLocale = async (locale: string) => {
+  if (locale === 'ja_JP') {
+    return (await import('./translations/ja_JP.json')).default.ja_JP;
+  }
+  return {};
+};
+
+const translations = {
+  [userLocale]: await loadLocale(userLocale),
+};
+
+const LocaleContext = createLocaleContext({
+  availableLanguages,
+  clientLocales: [userLocale, navigator.language, ...navigator.languages],
+  loadLocale,
+  translations,
+});
+```
+
+If you have to wait for data from your server to determine the user's locale, you can use the `setLocale` function provided by `useLocaleContext` to set the locale after the initial render:
+
+```tsx
+import { useLocaleContext } from 'fbtee';
+
+const Root = () => {
+  // Fetch the locale from the server.
+  const userLocale = useUserLocale();
+  const { locale, setLocale } = useLocaleContext();
+
+  useEffect(() => {
+    if (locale !== userLocale) {
+      setLocale(userLocale);
+    }
+  }, [locale, setLocale, userLocale]);
+
+  return children;
+};
+```
 
 ## ESLint Plugin
 
@@ -401,7 +629,7 @@ If you want stricter enforcement of translation rules, you can use the strict co
 }
 ```
 
-Or, if you'd like more granular control over the rules:
+Alternatively, if you'd like more granular control over the rules:
 
 ```js
 {
@@ -423,7 +651,7 @@ The open-source version of `fbt`, however, became unmaintained, difficult to set
 - **Easier Setup:** fbtee works with modern tools like Vite.
 - **Statically Typed:** The fbtee compiler ensures correct usage of fbtee, library TypeScript types are provided, and an eslint plugin helps fix common mistakes.
 - **Improved React Compatibility:** Removed React-specific hacks and added support for implicit React fragments (`<>`).
-- **Enhanced Features:** Fixed and exported `inltList` as a new `<fbt:list>` construct, which was not functional in the original `fbt`.
+- **Enhanced Features:** Fixed and exported `intlList` as a new `<fbt:list>` construct, which was not functional in the original `fbt`.
 - **Modernized Codebase:** Rewritten using TypeScript, ES modules (ESM), eslint, and modern JavaScript standards. Removed cruft and legacy code.
 - **Updated Tooling:** Uses modern tools like pnpm, Vite, and esbuild for faster and more efficient development of **fbtee**.
 

package/lib/index.cjs

@@ -25,7 +25,7 @@ const __typescript_eslint_utils = __toESM(require("@typescript-eslint/utils"));
 
 //#region package.json
 var name = "@nkzw/eslint-plugin-fbtee";
-var version = "1.2.2";
+var version = "1.2.6";
 var description = "";
 var keywords = [];
 var repository = {

package/lib/index.js

@@ -2,7 +2,7 @@ import { ESLintUtils } from "@typescript-eslint/utils";
 
 //#region package.json
 var name = "@nkzw/eslint-plugin-fbtee";
-var version = "1.2.2";
+var version = "1.2.6";
 var description = "";
 var keywords = [];
 var repository = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nkzw/eslint-plugin-fbtee",
-  "version": "1.2.2",
+  "version": "1.2.6",
   "description": "",
   "keywords": [],
   "repository": {