docs(README.md): update usage instructions and examples for clarity and accuracy

1. Clarify that the default translation is to English.
2. Remove redundant examples.
3. Change `--output` to `--out` to match actual command.
4. Add `--update` option and detailed example to show how to use it.
5. Expand explanation for `--preserve` option.
6. Remove redundant examples for `--verbose` and `--help` options.

Author: bounoable

README.md

@@ -41,10 +41,10 @@ The basic usage of Dragoman is as follows:
 dragoman source.json
 ```
 
-This command will translate the content of `source.json` and print the
-translated document to stdout. The source language is automatically detected by
-default, but if you want to specify the source or target languages, you need to
-use the `--from` or `--to` option.
+This command will translate the content of `source.json` to English and print
+the translated document to stdout. The source language is automatically detected
+by default, but if you want to specify the source or target languages, you need
+to use the `--from` or `--to` option.
 
 ### Full list of available options
 
@@ -54,10 +54,8 @@ The source language of the document. It can be specified in any format that a
 human would understand (like 'English', 'German', 'French', etc.). If not
 provided, it defaults to 'auto', meaning the language is automatically detected.
 
-Example:
-
 ```bash
-dragoman source.json --from English --to French
+dragoman source.json --from English
 ```
 
 **`-t` or `--to`**
@@ -66,46 +64,85 @@ The target language to which the document will be translated. It can be
 specified in any format that a human would understand (like 'English', 'German',
 'French', etc.). If not provided, it defaults to 'English'.
 
-Example:
-
 ```bash
 dragoman source.json --to French
 ```
 
-**`-o` or `--output`**
+**`-o` or `--out`**
 
 The path to the output file where the translated content will be saved. If this
 option is not provided, the translated content will be printed to stdout.
 
-Example:
+```bash
+dragoman source.json --out target.json
+```
+
+**`-u` or `--update`**
+
+Enable this option to only translate missing fields from the source file that
+are missing in the output file. This option requires the source and output files
+to be JSON!
 
 ```bash
-dragoman source.json --output target.json
+dragoman source.json --out target.json --update
 ```
 
-**`-p` or `--preserve`**
+#### Example
 
-A comma-separated list of words or terms that should not be translated.
-The preserved words will be recognized not only as stand-alone words but also as
-part of larger expressions. This could be useful, for example, when the known
-word is embedded within HTML tags or combined with other words. 
+When you add new translations to your JSON source file, you can use the `--update`
+option to only translate the newly added fields and merge them into the output file.
 
-Example:
+```json
+// en.json
+{
+	"hello": "Hello, world!",
+	"contact": {
+		"email": "[email protected]",
+		"response": "Thank you for your message."
+	}
+}
+```
+
+```json
+// de.json
+{
+	"hello": "Hallo, Welt!",
+	"contact": {
+		"email": "[email protected]"
+	}
+}
+```
 
 ```bash
-dragoman source.json --preserve Dragoman
+dragoman en.json --out de.json --update
 ```
 
-In this example, a term like `<span class="font-bold">Drago</span>man` will not
-be translated.
+Result:
+
+```json
+// de.json
+{
+	"hello": "Hallo, Welt!",
+	"contact": {
+		"email": "[email protected]",
+		"response": "Vielen Dank für deine Nachricht."
+	}
+}
+```
+
+**`-p` or `--preserve`**
+
+This option allows you to specify a list of specific words or phrases, separated by commas, that you want to remain unchanged during the translation process. It's particularly useful for ensuring that certain terms, which may have significance in their original form or are used in specific contexts (like code, trademarks, or names), are not altered. These specified terms will be recognized and preserved whether they appear in isolation or as part of larger strings. This feature is especially handy for content that includes embedded terms within other elements, such as HTML tags. For instance, using --preserve ensures that a term like <span class="font-bold">Drago</span>man retains its original form post-translation. Note that the effectiveness of this feature may vary depending on the language model used, and it is optimized for use with OpenAI's GPT models.
+
+```bash
+dragoman source.json --preserve Dragoman
+```
 
 **`-v` or `--verbose`**
 
 A flag that, if provided, makes the CLI provide more detailed output about the
 process and result of the translation.
 
-Example:
-
 ```bash
 dragoman source.json --verbose
 ```
@@ -114,8 +151,6 @@ dragoman source.json --verbose
 
 A flag that displays a help message detailing how to use the command and its options.
 
-Example:
-
 ```bash
 dragoman --help
 ```