Skip to content

The Open Source DocuSign Alternative.

chore: add docs for translations (#1310)

David Nguyen0298e79e8c43
diff --git a/apps/documentation/pages/developers/local-development/_meta.json b/apps/documentation/pages/developers/local-development/_meta.json
index ff9f44207..725e5e278 100644
--- a/apps/documentation/pages/developers/local-development/_meta.json
+++ b/apps/documentation/pages/developers/local-development/_meta.json
@@ -3,5 +3,6 @@
"quickstart": "Developer Quickstart",
"manual": "Manual Setup",
"gitpod": "Gitpod",
- "signing-certificate": "Signing Certificate"
-}
+ "signing-certificate": "Signing Certificate",
+ "translations": "Translations"
+}
\ No newline at end of file
diff --git a/apps/documentation/pages/developers/local-development/translations.mdx b/apps/documentation/pages/developers/local-development/translations.mdx
new file mode 100644
index 000000000..a776dc50c
--- /dev/null
+++ b/apps/documentation/pages/developers/local-development/translations.mdx
@@ -0,0 +1,128 @@
+---
+title: Translations
+description: Handling translations in code.
+---
+
+# About
+
+Documenso uses the following stack to handle translations:
+
+- [Lingui](https://lingui.dev/) - React i10n library
+- [Crowdin](https://crowdin.com/) - Handles syncing translations
+- [OpenAI](https://openai.com/) - Provides AI translations
+
+Additional reading can be found in the [Lingui documentation](https://lingui.dev/introduction).
+
+## Requirements
+
+You **must** insert **`setupI18nSSR()`** when creating any of the following files:
+
+- Server layout.tsx
+- Server page.tsx
+- Server loading.tsx
+
+Server meaning it does not have `'use client'` in it.
+
+```tsx
+import { setupI18nSSR } from '@documenso/lib/client-only/providers/i18n.server';
+
+export default function SomePage() {
+ setupI18nSSR(); // Required if there are translations within the page, or nested in components.
+
+ // Rest of code...
+}
+```
+
+Additional information can be found [here.](https://lingui.dev/tutorials/react-rsc#pages-layouts-and-lingui)
+
+## Quick guide
+
+If you require more in-depth information, please see the [Lingui documentation](https://lingui.dev/introduction).
+
+### HTML
+
+Wrap all text to translate in **`<Trans></Trans>`** tags exported from **@lingui/macro** (not @lingui/react).
+
+```html
+<h1>
+ <Trans>Title</Trans>
+</h1>
+```
+
+For text that is broken into elements, but represent a whole sentence, you must wrap it in a Trans tag so ensure the full message is extracted correctly.
+
+```html
+<h1>
+ <Trans>
+ This is one
+ <span className="text-foreground/60">full</span>
+ <a href="https://documenso.com">sentence</a>
+ </Trans>
+</h1>
+```
+
+### Constants outside of react components
+
+```tsx
+import { Trans, msg } from '@lingui/macro';
+import { useLingui } from '@lingui/react';
+
+// Wrap text in msg`text to translate` when it's in a constant here, or another file/package.
+export const CONSTANT_WITH_MSG = {
+ foo: msg`Hello`,
+ bar: msg`World`,
+};
+
+export const SomeComponent = () => {
+ const { _ } = useLingui();
+
+ return (
+ <div>
+ {/* This will render the correct translated text. */}
+ <p>{_(CONSTANT_WITH_MSG.foo)}</p>
+ </div>
+ );
+};
+```
+
+### Plurals
+
+Lingui provides a Plural component to make it easy. See full documentation [here.](https://lingui.dev/ref/macro#plural-1)
+
+```tsx
+// Basic usage.
+<Plural one="1 Recipient" other="# Recipients" value={recipients.length} />
+```
+
+### Dates
+
+Lingui provides a [DateTime instance](https://lingui.dev/ref/core#i18n.date) with the configured locale.
+
+#### Server components
+
+Note that the i18n instance is coming from **setupI18nSSR**.
+
+```tsx
+import { Trans } from '@lingui/macro';
+import { useLingui } from '@lingui/react';
+
+export const SomeComponent = () => {
+ const { i18n } = setupI18nSSR();
+
+ return <Trans>The current date is {i18n.date(new Date(), { dateStyle: 'short' })}</Trans>;
+};
+```
+
+#### Client components
+
+Note that the i18n instance is coming from the **import**.
+
+```tsx
+import { i18n } from '@lingui/core';
+import { Trans } from '@lingui/macro';
+import { useLingui } from '@lingui/react';
+
+export const SomeComponent = () => {
+ return <Trans>The current date is {i18n.date(new Date(), { dateStyle: 'short' })}</Trans>;
+};
+```