From a4e8f851cfb9e31e4edd1f92d8309de33b662304 Mon Sep 17 00:00:00 2001
From: Hamed Mohamed <hamedmohamed22w@gmail.com>
Date: Sat, 31 Jan 2026 22:38:17 +0300
Subject: [PATCH] feat(i18n): #620 add force option to setLocalLang

---
 .changeset/fast-foxes-sing.md     |  5 +++++
 workspaces/i18n/README.md         | 24 ++++++++++++++++++++++--
 workspaces/i18n/src/index.ts      | 16 ++++++++++++++--
 workspaces/i18n/test/i18n.spec.ts | 20 ++++++++++++++++++++
 4 files changed, 61 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/fast-foxes-sing.md

diff --git a/.changeset/fast-foxes-sing.md b/.changeset/fast-foxes-sing.md
new file mode 100644
index 00000000..47b07e21
--- /dev/null
+++ b/.changeset/fast-foxes-sing.md
@@ -0,0 +1,5 @@
+---
+"@nodesecure/i18n": minor
+---
+
+feat: add force option to setLocalLang
diff --git a/workspaces/i18n/README.md b/workspaces/i18n/README.md
index 1690a61e..46ef9b61 100644
--- a/workspaces/i18n/README.md
+++ b/workspaces/i18n/README.md
@@ -49,8 +49,13 @@ See TypeScript definition file.
 ```ts
 type languages = "french" | "english";
 
+interface SetLocalLangOptions {
+  /** If true, calls getLocalLang() after setting and returns the language. */
+  force?: boolean;
+}
+
 export function getLocalLang(): Promise<languages>;
-export function setLocalLang(newLanguage: languages): Promise<void>;
+export function setLocalLang(newLanguage: languages, options?: SetLocalLangOptions): Promise<languages | void>;
 export function getToken(token: string, ...parameters): Promise<string>;
 export function getTokenSync(token: string, ...parameters): string;
 export function getLanguages(): Promise<languages[]>;
@@ -59,8 +64,23 @@ export function extend(language: string, tokens: Record<string, any>): void;
 export function extendFromSystemPath(path: string): Promise<void>;
 ```
 
+### Using the `force` option
+
+Instead of calling `setLocalLang` and `getLocalLang` separately:
+
+```js
+await i18n.setLocalLang("french");
+await i18n.getLocalLang();
+```
+
+You can use the `force` option to do it in one call:
+
+```js
+await i18n.setLocalLang("french", { force: true });
+```
+
 > [!NOTE]
-> Local lang must be updated otherwise `getTokenSync()` will throws. Make sure to use `await i18n.getLocalLang()` before any synchronous usage.
+> Local lang must be updated otherwise `getTokenSync()` will throws. Make sure to use `await i18n.getLocalLang()` or `await i18n.setLocalLang(lang, { force: true })` before any synchronous usage.
 
 ## Generate documentation
 
diff --git a/workspaces/i18n/src/index.ts b/workspaces/i18n/src/index.ts
index dfa5056c..7416580c 100644
--- a/workspaces/i18n/src/index.ts
+++ b/workspaces/i18n/src/index.ts
@@ -35,11 +35,23 @@ export async function getLocalLang(): Promise<Languages> {
   return CONSTANTS.CURRENT_LANG;
 }
 
+export interface SetLocalLangOptions {
+  /** If true, calls getLocalLang() after setting and returns the language. */
+  force?: boolean;
+}
+
 export async function setLocalLang(
-  selectedLang: Languages
-): Promise<void> {
+  selectedLang: Languages,
+  options?: SetLocalLangOptions
+): Promise<Languages | void> {
   await cacache.put(CACHE_PATH, "cli-lang", selectedLang);
   CONSTANTS.LANG_UPDATED = true;
+
+  if (options?.force) {
+    return getLocalLang();
+  }
+
+  return undefined;
 }
 
 export async function getLanguages(): Promise<string[]> {
diff --git a/workspaces/i18n/test/i18n.spec.ts b/workspaces/i18n/test/i18n.spec.ts
index 09486803..1a1c68f2 100644
--- a/workspaces/i18n/test/i18n.spec.ts
+++ b/workspaces/i18n/test/i18n.spec.ts
@@ -43,6 +43,26 @@ describe("getLocalLang/setLocalLang", () => {
     assert.strictEqual(languages[0], "french");
     assert.strictEqual(languages[1], "english");
   });
+
+  it("setLocalLang with force option returns language and updates LANG_UPDATED", async() => {
+    await i18n.setLocalLang("english");
+    await i18n.getLocalLang();
+
+    const result = await i18n.setLocalLang("french", { force: true });
+
+    assert.strictEqual(result, "french");
+    assert.strictEqual(i18n.CONSTANTS.LANG_UPDATED, false);
+    assert.strictEqual(i18n.CONSTANTS.CURRENT_LANG, "french");
+  });
+
+  it("setLocalLang without force option returns undefined", async() => {
+    const result = await i18n.setLocalLang("english");
+
+    assert.strictEqual(result, undefined);
+    assert.strictEqual(i18n.CONSTANTS.LANG_UPDATED, true);
+
+    await i18n.setLocalLang("french");
+  });
 });
 
 describe("getToken", () => {