chore: update README

Author: wan2land

.vscode/settings.json

@@ -6,6 +6,9 @@
   "cSpell.words": [
     "deno",
     "denostack",
-    "intlit"
+    "intlit",
+    "Jaeum",
+    "jongseong",
+    "josa"
   ]
 }

README.md

@@ -24,6 +24,10 @@ TypeScript support.
 - Includes pluralization support (plugins can be optionally added for more
   features)
 - Easy to integrate with existing projects
+- Inline `/* ... */` comments let you differentiate identical source strings
+  without affecting the fallback text
+- Bundled Korean tagged template adds automatic particle selection when `locale`
+  is set to `ko`
 
 ## Installation
 
@@ -49,6 +53,36 @@ const text = formatter.format("Hello World");
 console.log(text); // Output: Hello World
 ```
 
+You can pass values in the second argument and interpolate them inside the
+template. When no translation is registered, the original text is used as the
+fallback.
+
+```typescript
+const formatter = new Formatter({ locale: "en" });
+
+formatter.format("Hello, {name}!", { name: "Kelly" });
+// → "Hello, Kelly!"
+```
+
+### Supplying Localized Messages
+
+Provide a message catalog to translate strings. The `Formatter` generics keep
+the message keys type-safe.
+
+```typescript
+const messages = {
+  "Hello, {name}!": "안녕하세요, {name}!",
+};
+
+const formatter = new Formatter<typeof messages>({
+  locale: "ko",
+  messages,
+});
+
+formatter.format("Hello, {name}!", { name: "Kelly" });
+// → "안녕하세요, Kelly!"
+```
+
 ### Handling Plurals
 
 Intlit provides support for handling plural forms in different languages, making
@@ -127,3 +161,122 @@ console.log(
   formatter.format("You have {count} file{count.other:}s{/}.", { count: 100 }),
 ); // Output: لديك 100 ملفات.
 ```
+
+### Gender and Conditional Segments
+
+Hooks in Intlit behave like chained methods. The default hooks include helpers
+for gendered output and `else` fallbacks.
+
+```typescript
+const formatter = new Formatter({ locale: "en" });
+
+formatter.format(
+  "{user} added {photoCount.one:}a new photo{.other:}{_} new photos{/} to {gender.male:}his{.female:}her{.other:}their{/} stream.",
+  { user: "Alex", photoCount: 2, gender: "female" },
+);
+// → "Alex added 2 new photos to her stream."
+```
+
+Inside nested segments the current value is available through the special `_`
+parameter, so you can reuse the original number (as seen above when printing the
+plural count).
+
+### Adding Context with Inline Comments
+
+Inline block comments are stripped from the rendered output but kept in the key.
+They are perfect for differentiating identical phrases that need distinct
+translations.
+
+```typescript
+const messages = {
+  "/* 환영 */안녕하세요.": "Welcome!",
+  "/* 일반 */안녕하세요.": "Hello!",
+};
+
+const formatter = new Formatter({
+  locale: "en",
+  messages,
+});
+
+formatter.format("/* 환영 */안녕하세요.");
+// → "Welcome!"
+
+formatter.format("/* 일반 */안녕하세요.");
+// → "Hello!"
+
+// Because the comments are ignored at runtime the fallback remains clean.
+new Formatter({ locale: "ko" }).format("/* 환영 */안녕하세요.");
+// → "안녕하세요."
+```
+
+### Integrating a Tagged Template Handler
+
+Need smarter whitespace management or language-specific post-processing? Intlit
+ships with a particle-aware template handler that is applied automatically when
+`locale` is set to `ko`.
+
+```typescript
+const formatter = new Formatter({ locale: "ko" });
+
+formatter.format(
+  `새 소식이 있습니다:\n{count.one:}새 메시지가 하나 생겼어요{.other:}{_}개의 새 메시지가 있어요{/}
+`,
+  { count: 3 },
+);
+// → "새 소식이 있습니다:\n3개의 새 메시지가 있어요"
+```
+
+For other locales you can still provide your own `taggedTemplate` function to
+massage the final string (e.g. trim indentation, collapse whitespace, or run
+additional transforms).
+
+### Custom Hooks
+
+Extend Intlit by adding application-specific hooks. A hook receives a
+`HookContext` object describing the current placeholder and returns the next
+value that should flow through the chain.
+
+```typescript
+import { Formatter, type Hook } from "intlit";
+
+const upper: Hook = (ctx) => String(ctx.current ?? "").toUpperCase();
+
+const fallback: Hook = (ctx) =>
+  ctx.current == null || ctx.current === "" ? "(none)" : ctx.current;
+
+const formatter = new Formatter({
+  locale: "en",
+  hooks: { upper, fallback },
+});
+
+formatter.format("Hello, {name.upper.fallback}!", { name: "alex" });
+// → "Hello, ALEX!"
+```
+
+Hooks receive:
+
+- `ctx.original`: The value that came directly from `Formatter#format`.
+- `ctx.current`: The value produced so far in the chain. Whatever the hook
+  returns becomes the new `ctx.current`.
+- `ctx.locale`: Locale that was supplied when constructing the formatter.
+- `args`: Arguments passed from the template method such as the `currency` part
+  in `{price.number:currency}`. Arguments can include nested templates.
+
+To share state across hook invocations, keep data in a
+`WeakMap<HookContext, …>`. The built-in gender and plural hooks follow this
+pattern to remember which branch has already matched.
+
+Combine custom hooks with the built-in plural helpers to cover complex cases
+without branching in your code.
+
+## Formatter Options
+
+`new Formatter(options)` accepts the following configuration:
+
+- `locale`: Locale passed to plural rules. Defaults to `en`.
+- `messages`: A record of source text → translated text pairs.
+- `hooks`: Extra hook implementations that augment or replace the defaults.
+- `taggedTemplate`: Custom renderer for the template literal output.
+
+Instantiate different `Formatter` objects per locale, or swap the `messages`
+object dynamically when building multi-locale applications.

deno.json

@@ -12,7 +12,6 @@
   },
   "imports": {
     "@deno/dnt": "jsr:@deno/dnt@^0.41.1",
-    "@kokr/text": "npm:@kokr/text@^0.4.1",
     "@std/assert": "jsr:@std/assert@^0.222.1",
     "@std/fmt": "jsr:@std/fmt@^0.222.1",
     "@std/testing": "jsr:@std/testing@^0.222.1"

formatter.test.ts

@@ -1,4 +1,3 @@
-import { text } from "@kokr/text";
 import { assertEquals } from "@std/assert/assert-equals";
 import { Formatter } from "./formatter.ts";
 
@@ -37,7 +36,6 @@ Deno.test("formatter, plural", () => {
     const formatter = new Formatter({
       locale: "ko",
       messages: messages.ko,
-      taggedTemplate: text,
     });
 
     assertEquals(
@@ -91,3 +89,16 @@ Deno.test("formatter, plural", () => {
     );
   }
 });
+
+Deno.test("formatter, ko josa", () => {
+  const formatter = new Formatter({ locale: "ko" });
+
+  assertEquals(
+    formatter.format("{name}는 코딩합니다.", { name: "완두" }),
+    "완두는 코딩합니다.",
+  );
+  assertEquals(
+    formatter.format("{name}는 코딩합니다.", { name: "완삼" }),
+    "완삼은 코딩합니다.",
+  );
+});

formatter.ts

@@ -1,5 +1,6 @@
 import { defaultHooks } from "./default_hooks.ts";
 import { Interpreter } from "./interpreter.ts";
+import { template } from "./langs/ko/template.ts";
 import type {
   FormatParameters,
   Hook,
@@ -25,7 +26,8 @@ export class Formatter<Messages extends Record<string, string>> {
           ...defaultHooks,
           ...options.hooks,
         },
-        taggedTemplate: options.taggedTemplate,
+        taggedTemplate: options.taggedTemplate ??
+          (options.locale === "ko" ? template : undefined),
       },
     );
     this.messages = messages ?? {} as Messages;