Adds clarifications to README for new fbtee users (#20)

* docs: extends the current documentation to explain a few stumbling blocks * Iterate. --------- Co-authored-by: Tobias Steckenborn <tobias.steckenborn01@sap.com> Co-authored-by: cpojer <christoph.pojer@gmail.com>
nkzw-tech · Jan 8, 2025 · bebe599 · bebe599
1 parent 0ee210b
commit bebe599
Showing 1 changed file with 108 additions and 10 deletions.
diff --git a/README.md b/README.md
@@ -18,7 +18,13 @@ This is a fork of Facebook's original `fbt` library, which has been archived. Th
 **fbtee** requires at least Node 22, and React 19 if you are using React.
 
 ```bash
-npm install fbtee @nkzw/babel-preset-fbtee
+npm install fbtee
+```
+
+In addition to `fbtee`, you need to install the Babel preset and React plugin for Vite:
+
+```bash
+npm install -D @nkzw/babel-preset-fbtee @vitejs/plugin-react
 ```
 
 In your `vite.config.ts`:
@@ -43,20 +49,26 @@ export default {
 ```json
 {
   "scripts": {
-    "fbtee:collect": "fbtee collect --manifest < .src_manifest.json > .source_strings.json",
     "fbtee:manifest": "fbtee manifest --src src",
+    "fbtee:collect": "fbtee collect --manifest < .src_manifest.json > .source_strings.json",
     "fbtee:translate": "fbtee translate --translations translations/*.json --jenkins > src/translations.json"
   }
 }
 ```
 
-Run these commands to set up the initial translation files:
+Here is what each command does:
+
+- `fbtee manifest --src src` searches through files in the `src` directory and generates a manifest file (`.src_manifest.json`) that lists all the files translatable strings marked with `<fbt>`. In addition it creates `.enum_manifest.json` which lists all the files containing `<fbt:enum>` tags. Since these files are auto-generated, we recommend adding them to your `.gitignore`.
+- `fbtee collect --manifest < .src_manifest.json > .source_strings.json` reads the manifest file and extracts all the strings marked for translation into a `.source_strings.json` file. This file should be uploaded to your translation provider as the source for your translations.
+- `fbtee translate --translations translations/*.json --jenkins > src/translations.json` reads all the translations in the `translations/` directory and compiles them into a single `src/translations.json` file. This file is used by **fbtee** to display translated content in your app. The `--translations` parameter specifies the path to the translation files. The `--jenkins` flag is used to define the utilized [hash function](https://en.wikipedia.org/wiki/Jenkins_hash_function). You can adjust the `--translations` parameter to point to your translation directory. If your translations are within your app directory in a folder called `i18n`, for example, you'd use `--translations app/i18n/*.json`. The output is the translation file used by **fbtee**. This file is going to be referred to in your applications entry point, therefor it needs to be generated as part of the build, but should not be part of version control. This command requires the translations to be present in the `translations/` directory, created based on real translations of what was previously collected using the `collect` command.
+
+Now, the first step is to run these commands to set up the initial strings for translation:
 
 ```bash
-npm run fbtee:manifest && npm run fbtee:collect && npm run fbtee:translate
+npm run fbtee:manifest && npm run fbtee:collect
 ```
 
-The files generated by these commands are auto-generated and should not be checked into version control. Add the following entries to your `.gitignore`:
+The files generated by these commands should be added to `.gitignore`:
 
 ```
 .src_manifest.json
@@ -82,13 +94,13 @@ setupFbtee({
 });
 ```
 
-Finally, if you are using React and TypeScript in your project, you need to add TypeScript types for **fbtee** to enable proper type checking in JSX. You can do this by referencing the `ReactTypes.d.ts` file in your main `index.tsx` file or a global type declaration file (e.g., `types.d.ts`):
+Next up, if you are using React and TypeScript in your project, you need to add TypeScript types for **fbtee** to enable proper type checking in JSX. You can do this by referencing the `ReactTypes.d.ts` file in your main `index.tsx` file or a global type declaration file (e.g., `types.d.ts`):
 
 ```tsx
 /// <reference types="fbtee/ReactTypes.d.ts" />
 ```
 
-_You’re now ready to go!_
+_You’re now ready to define your first translatable element!_
 
 ## Usage
 
@@ -141,16 +153,102 @@ _Note: `<fbt>` is auto-imported for you by the `@nkzw/babel-preset-fbtee` plugin
 After marking your strings for translation with `<fbt>`, run the following commands to extract, and compile translations:
 
 ```bash
-npm run fbtee:collect
+npm run fbtee:manifest && npm run 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/).
+
+### Generated File Structure
+
+Your `.source_strings.json` might look like this:
+
+```json
+{
+  "childParentMappings": {},
+  "phrases": [
+    {
+      "hashToLeaf": {
+        "MB6OYuvCF1VzjOmqinI42g==": {
+          "desc": "What's next question",
+          "text": "What's next?"
+        }
+      },
+      "col_beg": 12,
+      "col_end": 68,
+      "filepath": "app/welcome/welcome.tsx",
+      "line_beg": 43,
+      "line_end": 43,
+      "project": "",
+      "jsfbt": {
+        "m": [],
+        "t": {
+          "desc": "What's next question",
+          "text": "What's next?"
+        }
+      }
+    }
+  ]
+}
+```
+
+Based on the above source string, the US English translation (ie. `translations/en_US.json`) might look like this:
+
+```json
+{
+  "fb-locale": "en_US",
+  "translations": {
+    "MB6OYuvCF1VzjOmqinI42g==": {
+      "tokens": [],
+      "types": [],
+      "translations": [
+        {
+          "translation": "What's next?",
+          "variations": []
+        }
+      ]
+    }
+  }
+}
 ```
 
-You can now upload the `.source_strings.json` file to your translation provider. 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:
+And German (`translations/de_DE.json`) might look like this:
+
+```json
+{
+  "fb-locale": "de_DE",
+  "translations": {
+    "MB6OYuvCF1VzjOmqinI42g==": {
+      "tokens": [],
+      "types": [],
+      "translations": [
+        {
+          "translation": "Was kommt jetzt?",
+          "variations": []
+        }
+      ]
+    }
+  }
+}
+```
+
+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:
 
 ```bash
 npm run fbtee:translate
 ```
 
-After generating the translations file, your app is ready to display translated content in other languages.
+This will generate the `translation.json` file referred to in the setup done before. This file might look like this:
+
+```json
+{
+  "de_DE": { "2HVYhv": "Was kommt jetzt?" },
+  "en_US": { "2HVYhv": "What's next?" }
+}
+```
+
+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.
+
+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.
 
 ## ESLint Plugin