@intlayer/docs 7.0.6 → 7.0.8-canary.0

package/docs/id/packages/next-intlayer/t.md

@@ -0,0 +1,352 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Dokumentasi Fungsi t | next-intlayer
+description: Lihat cara menggunakan fungsi t untuk paket next-intlayer
+keywords:
+  - t
+  - terjemahan
+  - Intlayer
+  - next-intlayer
+  - Internasionalisasi
+  - Dokumentasi
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - next-intlayer
+  - t
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Inisialisasi riwayat
+---
+
+# Dokumentasi: Fungsi `t` di `next-intlayer`
+
+Fungsi `t` dalam paket `next-intlayer` adalah alat fundamental untuk internasionalisasi inline dalam aplikasi Next.js Anda. Fungsi ini memungkinkan Anda mendefinisikan terjemahan langsung di dalam komponen Anda, sehingga memudahkan untuk menampilkan konten yang dilokalisasi berdasarkan locale saat ini.
+
+---
+
+## Ikhtisar
+
+Fungsi `t` digunakan untuk menyediakan terjemahan untuk berbagai locale langsung di dalam komponen Anda. Dengan melewatkan sebuah objek yang berisi terjemahan untuk setiap locale yang didukung, `t` mengembalikan terjemahan yang sesuai berdasarkan konteks locale saat ini dalam aplikasi Next.js Anda.
+
+---
+
+## Fitur Utama
+
+- **Terjemahan Inline**: Ideal untuk teks cepat dan inline yang tidak memerlukan deklarasi konten terpisah.
+- **Pemilihan Locale Otomatis**: Mengembalikan terjemahan yang sesuai dengan locale saat ini secara otomatis.
+- **Dukungan TypeScript**: Menyediakan keamanan tipe dan autocompletion saat digunakan dengan TypeScript.
+- **Integrasi Mudah**: Bekerja dengan mulus di dalam komponen client dan server di Next.js.
+
+---
+
+## Tanda Tangan Fungsi
+
+```typescript
+t<T extends string>(content: Record<LocalesValues, T>, locale?: Locales): string
+```
+
+### Parameter
+
+- `translations`: Sebuah objek di mana kunci adalah kode locale (misalnya, `en`, `fr`, `es`) dan nilainya adalah string terjemahan yang sesuai.
+
+### Mengembalikan
+
+- Sebuah string yang mewakili konten terjemahan untuk locale saat ini.
+
+---
+
+## Contoh Penggunaan
+
+### Menggunakan `t` dalam Komponen Client
+
+Pastikan Anda menyertakan direktif `'use client';` di bagian atas file komponen Anda saat menggunakan `t` dalam komponen sisi client.
+
+```tsx codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { t } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido d un ejemplo de componente cliente",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer";
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido d un ejemplo de componente cliente",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es le contenido d un ejemplo de componente cliente",
+    })}
+  </p>
+);
+```
+
+### Menggunakan `t` dalam Komponen Server
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "next-intlayer/server";
+
+export const ServerComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer/server";
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer/server");
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+    })}
+  </p>
+);
+```
+
+### Terjemahan Inline dalam Atribut
+
+Fungsi `t` sangat berguna untuk terjemahan inline dalam atribut JSX.
+Saat melokalkan atribut seperti `alt`, `title`, `href`, atau `aria-label`, Anda dapat menggunakan `t` langsung di dalam atribut.
+
+```jsx
+<button
+  aria-label={t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+  })}
+>
+  {t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+  })}
+  <img
+    src="/path/to/image"
+    alt={t({
+      en: "A beautiful scenery",
+      fr: "Un beau paysage",
+      es: "Un hermoso paisaje",
+    })}
+  />
+</button>
+```
+
+---
+
+## Topik Lanjutan
+
+### Integrasi TypeScript
+
+Fungsi `t` aman secara tipe saat digunakan dengan TypeScript, memastikan semua locale yang diperlukan disediakan.
+
+```typescript codeFormat="typescript"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+### Deteksi Locale dan Konteks
+
+Dalam `next-intlayer`, locale saat ini dikelola melalui context providers: `IntlayerClientProvider` dan `IntlayerServerProvider`. Pastikan provider ini membungkus komponen Anda dan properti `locale` diteruskan dengan benar.
+
+#### Contoh:
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Komponen Anda di sini */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="esm"
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Komponen Anda di sini */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { IntlayerClientProvider } = require("next-intlayer");
+const { IntlayerServerProvider } = require("next-intlayer/server");
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Komponen Anda di sini */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+---
+
+## Kesalahan Umum dan Pemecahan Masalah
+
+### `t` Mengembalikan Undefined atau Terjemahan yang Salah
+
+- **Penyebab**: Locale saat ini tidak diatur dengan benar, atau terjemahan untuk locale saat ini tidak ada.
+- **Solusi**:
+  - Pastikan bahwa `IntlayerClientProvider` atau `IntlayerServerProvider` telah diatur dengan benar menggunakan `locale` yang sesuai.
+  - Pastikan bahwa objek terjemahan Anda mencakup semua locale yang diperlukan.
+
+### Terjemahan Hilang di TypeScript
+
+- **Penyebab**: Objek terjemahan tidak memenuhi locale yang diperlukan, menyebabkan error TypeScript.
+- **Solusi**: Gunakan tipe `IConfigLocales` untuk memastikan kelengkapan terjemahan Anda.
+
+```typescript codeFormat="typescript"
+const translations: IConfigLocales<string> = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Hilangnya 'es' akan menyebabkan error TypeScript [!code error]
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="esm"
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Hilangnya 'es' akan menyebabkan error TypeScript [!code error]
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Hilangnya 'es' akan menyebabkan error TypeScript [!code error]
+};
+
+const text = t(translations);
+```
+
+---
+
+## Tips untuk Penggunaan Efektif
+
+1. **Gunakan `t` untuk Terjemahan Inline Sederhana**: Ideal untuk menerjemahkan potongan teks kecil langsung di dalam komponen Anda.
+2. **Lebih Pilih `useIntlayer` untuk Konten Terstruktur**: Untuk terjemahan yang lebih kompleks dan penggunaan ulang konten, definisikan konten dalam file deklarasi dan gunakan `useIntlayer`.
+3. **Penyediaan Locale yang Konsisten**: Pastikan locale Anda disediakan secara konsisten di seluruh aplikasi melalui penyedia yang sesuai.
+4. **Manfaatkan TypeScript**: Gunakan tipe TypeScript untuk menangkap terjemahan yang hilang dan memastikan keamanan tipe.
+
+---
+
+## Kesimpulan
+
+Fungsi `t` dalam `next-intlayer` adalah alat yang kuat dan praktis untuk mengelola terjemahan inline dalam aplikasi Next.js Anda. Dengan mengintegrasikannya secara efektif, Anda meningkatkan kemampuan internasionalisasi aplikasi Anda, memberikan pengalaman yang lebih baik bagi pengguna di seluruh dunia.
+
+Untuk penggunaan yang lebih rinci dan fitur lanjutan, lihat [dokumentasi next-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/intlayer_visual_editor.md).
+
+---
+
+**Catatan**: Ingatlah untuk mengatur `IntlayerClientProvider` dan `IntlayerServerProvider` Anda dengan benar agar locale saat ini diteruskan dengan tepat ke komponen Anda. Ini sangat penting agar fungsi `t` mengembalikan terjemahan yang benar.

package/docs/id/packages/next-intlayer/useDictionary.md

@@ -0,0 +1,271 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Dokumentasi Hook useDictionary | next-intlayer
+description: Lihat cara menggunakan hook useDictionary untuk paket next-intlayer
+keywords:
+  - useDictionary
+  - kamus
+  - kunci
+  - Intlayer
+  - Internasionalisasi
+  - Dokumentasi
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - next-intlayer
+  - useDictionary
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Inisialisasi riwayat
+---
+
+# Integrasi React: Dokumentasi Hook `useDictionary`
+
+Bagian ini memberikan panduan rinci tentang penggunaan hook `useDictionary` dalam aplikasi React, memungkinkan penanganan konten yang dilokalisasi secara efisien tanpa editor visual.
+
+## Mengimpor `useDictionary` di React
+
+Hook `useDictionary` dapat diintegrasikan ke dalam aplikasi React dengan mengimpornya berdasarkan konteks:
+
+- **Komponen Klien:**
+
+  ```typescript codeFormat="typescript"
+  import { useDictionary } from "next-intlayer"; // Digunakan dalam komponen React sisi klien
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useDictionary } from "next-intlayer"; // Digunakan dalam komponen React sisi klien
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useDictionary } = require("next-intlayer"); // Digunakan dalam komponen React sisi klien
+  ```
+
+- **Komponen Server:**
+
+  ```typescript codeFormat="typescript"
+  import { useDictionary } from "next-intlayer/server"; // Digunakan dalam komponen React sisi server
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useDictionary } from "next-intlayer/server"; // Digunakan dalam komponen React sisi server
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useDictionary } = require("next-intlayer/server"); // Digunakan dalam komponen React sisi server
+  ```
+
+## Parameter
+
+Hook ini menerima dua parameter:
+
+1. **`dictionary`**: Objek kamus yang dideklarasikan berisi konten terlokalisasi untuk kunci tertentu.
+2. **`locale`** (opsional): Locale yang diinginkan. Defaultnya adalah locale dari konteks saat ini jika tidak ditentukan.
+
+## Kamus
+
+Semua objek kamus harus dideklarasikan dalam file konten terstruktur untuk memastikan keamanan tipe dan mencegah kesalahan saat runtime. Anda dapat menemukan [instruksi pengaturan di sini](https://github.com/aymericzip/intlayer/blob/main/docs/docs/id/dictionary/content_file.md). Berikut adalah contoh deklarasi konten:
+
+```typescript fileName="component.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    }),
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+```javascript fileName="component.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+// contoh deklarasi konten menggunakan format ESM
+const exampleContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    }),
+  },
+};
+
+export default exampleContent;
+```
+
+```javascript fileName="component.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+// contoh deklarasi konten menggunakan format CommonJS
+const exampleContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    }),
+  },
+};
+
+module.exports = exampleContent;
+```
+
+## Contoh Penggunaan di Komponen Client React
+
+Di bawah ini adalah contoh cara menggunakan hook `useDictionary` dalam sebuah komponen React:
+
+```tsx fileName="ClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useDictionary } from "next-intlayer";
+import clientComponentExampleContent from "./component.content";
+
+const ClientComponentExample: FC = () => {
+  const { title, content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ClientComponentExample.mjs" codeFormat="esm"
+"use client";
+
+import type { FC } from "react";
+import { useDictionary } from "next-intlayer";
+import exampleContent from "./component.content";
+
+const ClientComponentExample: FC = () => {
+  const { title, content } = useDictionary(exampleContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ClientComponentExample.cjs" codeFormat="commonjs"
+"use client";
+
+const { useDictionary } = require("next-intlayer");
+const exampleContent = require("./component.content");
+
+// Contoh komponen klien menggunakan useDictionary
+const ClientComponentExample = () => {
+  const { title, content } = useDictionary(exampleContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+## Contoh Penggunaan di React Server Component
+
+Jika Anda menggunakan hook `useDictionary` di luar `IntlayerServerProvider`, locale harus secara eksplisit diberikan sebagai parameter saat merender komponen:
+
+```tsx fileName="ServerComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useDictionary } from "next-intlayer/server";
+import clientComponentExampleContent from "./component.content";
+
+const ServerComponentExample: FC = () => {
+  const { content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ServerComponentExample.mjs" codeFormat="esm"
+import { useDictionary } from "next-intlayer/server";
+import clientComponentExampleContent from "./component.content";
+
+const ServerComponentExample = () => {
+  const { content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ServerComponentExample.cjs" codeFormat="commonjs"
+import { useDictionary } from "next-intlayer/server";
+import clientComponentExampleContent from "./component.content";
+
+const ServerComponentExample = () => {
+  const { content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+## Catatan tentang Atribut
+
+Berbeda dengan integrasi yang menggunakan editor visual, atribut seperti `buttonTitle.value` tidak berlaku di sini. Sebagai gantinya, akses langsung string yang sudah dilokalisasi seperti yang dideklarasikan dalam konten Anda.
+
+```jsx
+<button title={content.title}>{content.content}</button>
+```
+
+## Tips Tambahan
+
+- **Keamanan Tipe**: Selalu gunakan `Dictionary` untuk mendefinisikan kamus Anda agar memastikan keamanan tipe.
+- **Pembaruan Lokalisasi**: Saat memperbarui konten, pastikan semua locale konsisten untuk menghindari terjemahan yang hilang.
+
+Dokumentasi ini berfokus pada integrasi hook `useDictionary`, menyediakan pendekatan yang efisien untuk mengelola konten yang dilokalisasi tanpa bergantung pada fungsi editor visual.