framer · tom-james-watson · Jan 27, 2025 · Dec 3, 2024 · Dec 3, 2024 · Dec 6, 2024
diff --git a/package-lock.json b/package-lock.json
diff --git a/plugins/localization-import-export/README.md b/plugins/localization-import-export/README.md
@@ -0,0 +1,3 @@
+# Localization Import & Export
+
+Import and export your Framer localizations using the common XLIFF format.
diff --git a/plugins/localization-import-export/eslint.config.js b/plugins/localization-import-export/eslint.config.js
@@ -0,0 +1,32 @@
+import js from "@eslint/js"
+import globals from "globals"
+import reactHooks from "eslint-plugin-react-hooks"
+import reactRefresh from "eslint-plugin-react-refresh"
+import tseslint from "typescript-eslint"
+
+export default tseslint.config(
+    { ignores: ["dist"] },
+    {
+        extends: [js.configs.recommended, ...tseslint.configs.recommended],
+        files: ["**/*.{ts,tsx}"],
+        languageOptions: {
+            ecmaVersion: 2022,
+            globals: globals.browser,
+        },
+        plugins: {
+            "react-hooks": reactHooks,
+            "react-refresh": reactRefresh,
+        },
+        rules: {
+            ...reactHooks.configs.recommended.rules,
+            "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
+            "@typescript-eslint/no-unused-vars": [
+                "error",
+                {
+                    argsIgnorePattern: "^_",
+                    varsIgnorePattern: "^_$",
+                },
+            ],
+        },
+    }
+)
diff --git a/plugins/localization-import-export/framer.json b/plugins/localization-import-export/framer.json
@@ -0,0 +1,6 @@
+{
+    "id": "fc871f",
+    "name": "Locale Import & Export",
+    "modes": ["localization"],
+    "icon": "/icon.svg"
+}
diff --git a/plugins/localization-import-export/index.html b/plugins/localization-import-export/index.html
@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+  <html lang="en">
+    <head>
+      <meta charset="UTF-8" />
+      <link rel="icon" type="image/svg+xml" href="/icon.svg" />
+      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+      <title>Localization Import Export</title>
+    </head>
+    <body>
+      <div id="root"></div>
+      <script type="module" src="/src/main.tsx"></script>
+    </body>
+  </html>
+
diff --git a/plugins/localization-import-export/package.json b/plugins/localization-import-export/package.json
@@ -0,0 +1,34 @@
+{
+    "name": "localization-import-export",
+    "private": true,
+    "version": "0.0.0",
+    "type": "module",
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build --base=${PREFIX_BASE_PATH:+/$npm_package_name}/",
+        "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+        "preview": "vite preview",
+        "pack": "npx framer-plugin-tools@latest pack"
+    },
+    "dependencies": {
+        "framer-plugin": "^2.1.0",
+        "react": "^18",
+        "react-dom": "^18",
+        "vite-plugin-mkcert": "^1"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9",
+        "@types/react": "^18",
+        "@types/react-dom": "^18",
+        "@vitejs/plugin-react": "^4.3.1",
+        "@vitejs/plugin-react-swc": "^3",
+        "eslint": "^9.9.0",
+        "eslint-plugin-react-hooks": "^5.1.0-rc.0",
+        "eslint-plugin-react-refresh": "^0.4.9",
+        "globals": "^15.9.0",
+        "typescript": "^5.3",
+        "typescript-eslint": "^8.0.1",
+        "vite": "^5",
+        "vite-plugin-framer": "^1"
+    }
+}
diff --git a/plugins/localization-import-export/public/icon.svg b/plugins/localization-import-export/public/icon.svg
diff --git a/plugins/localization-import-export/src/App.css b/plugins/localization-import-export/src/App.css
@@ -0,0 +1,38 @@
+main {
+    --framer-color-tint: #00CCEE;
+    --framer-color-tint-dark: #00C6E6;
+    --framer-color-tint-extra-dark: #00BBDD;
+    display: flex;
+    flex-direction: column;
+    align-items: start;
+    padding: 0 15px 15px 15px;
+    height: 100%;
+    gap: 15px;
+}
+
+select {
+    width: 100%;
+}
+
+p {
+    color: var(--framer-color-text-tertiary);
+}
+
+.button-stack { 
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    gap: 10px;
+}
+
+.asset {
+    color: var(--framer-color-tint, rgb(0, 204, 238));
+    background: rgba(0, 204, 238, 0.1);
+    border-radius: 8px;
+    flex: 1;
+    width: 100%;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+}
+
diff --git a/plugins/localization-import-export/src/App.tsx b/plugins/localization-import-export/src/App.tsx
@@ -0,0 +1,124 @@
+import type { Locale } from "framer-plugin"
+
+import { framer } from "framer-plugin"
+import { useEffect, useState } from "react"
+import "./App.css"
+import { downloadBlob, importFileAsText } from "./files"
+import { createValuesBySourceFromXliff, generateXliff, parseXliff } from "./xliff"
+
+framer.showUI({
+    width: 300,
+    height: 350,
+})
+
+async function importXliff() {
+    importFileAsText(".xlf,.xliff", async (xliffText: string) => {
+        try {
+            const locales = await framer.unstable_getLocales()
+
+            const { xliff, targetLocale } = parseXliff(xliffText, locales)
+            const valuesBySource = createValuesBySourceFromXliff(xliff, targetLocale)
+
+            const result = await framer.unstable_setLocalizationData({ valuesBySource })
+
+            if (result.valuesBySource.errors.length > 0) {
+                throw new Error(`Import errors: ${result.valuesBySource.errors.map(error => error.error).join(", ")}`)
+            }
+
+            framer.notify(`Successfully imported localizations for ${targetLocale.name}`)
+        } catch (error) {
+            console.error(error)
+            framer.notify(error instanceof Error ? error.message : "Error importing XLIFF file", { variant: "error" })
+        }
+    })
+}
+
+async function exportXliff(defaultLocale: Locale, targetLocale: Locale) {
+    const filename = `locale_${targetLocale.code}.xlf`
+
+    try {
+        const groups = await framer.unstable_getLocalizationGroups()
+        const xliff = generateXliff(defaultLocale, targetLocale, groups)
+        downloadBlob(xliff, filename, "application/x-xliff+xml")
+
+        framer.notify(`Successfully exported ${filename}`)
+    } catch (error) {
+        console.error(error)
+        framer.notify(`Error exporting ${filename}`, { variant: "error" })
+    }
+}
+
+export function App() {
+    const [selectedLocaleId, setSelectedLocaleId] = useState<string>("")
+    const [locales, setLocales] = useState<readonly Locale[]>([])
+    const [defaultLocale, setDefaultLocale] = useState<Locale | null>(null)
+
+    const selectedLocale = locales.find(locale => locale.id === selectedLocaleId)
+
+    useEffect(() => {
+        async function loadLocales() {
+            const initialLocales = await framer.unstable_getLocales()
+            const initialDefaultLocale = await framer.unstable_getDefaultLocale()
+            setLocales(initialLocales)
+            setDefaultLocale(initialDefaultLocale)
+
+            const activeLocale = await framer.unstable_getActiveLocale()
+            if (activeLocale) {
+                setSelectedLocaleId(activeLocale.id)
+            }
+        }
+
+        loadLocales()
+    }, [])
+
+    async function handleExport() {
+        if (!selectedLocaleId || !defaultLocale) return
+
+        const targetLocale = locales.find(locale => locale.id === selectedLocaleId)
+        if (!targetLocale) {
+            throw new Error(`Could not find locale with id ${selectedLocaleId}`)
+        }
+
+        exportXliff(defaultLocale, targetLocale)
+    }
+
+    return (
+        <main>
+            <div className="asset">
+                <svg xmlns="http://www.w3.org/2000/svg" width="74" height="74">
+                    <path
+                        d="M 37 2.313 C 56.157 2.313 71.688 17.843 71.688 37 C 71.688 56.157 56.157 71.688 37 71.688 C 17.843 71.688 2.313 56.157 2.313 37 C 2.313 17.843 17.843 2.313 37 2.313 Z M 11.563 37 C 11.563 47.692 18.159 56.843 27.504 60.606 C 24.809 54.7 23.125 46.309 23.125 37 C 23.125 27.691 24.809 19.3 27.504 13.394 C 18.159 17.157 11.563 26.308 11.563 37 Z M 62.438 37 C 62.438 26.308 55.841 17.157 46.496 13.394 C 49.191 19.3 50.875 27.691 50.875 37 C 50.875 46.309 49.191 54.7 46.496 60.606 C 55.841 56.843 62.438 47.692 62.438 37 Z M 30.063 37 C 30.063 51.049 33.169 62.438 37 62.438 C 40.831 62.438 43.938 51.049 43.938 37 C 43.938 22.951 40.831 11.563 37 11.563 C 33.169 11.563 30.063 22.951 30.063 37 Z"
+                        fill="currentColor"
+                    ></path>
+                    <path
+                        d="M 6.937 34.688 L 6.938 34.688 C 26.719 39.253 47.281 39.253 67.063 34.688 L 67.063 34.688"
+                        fill="transparent"
+                        strokeWidth="7"
+                        stroke="currentColor"
+                        stroke-linecap="round"
+                        stroke-linejoin="round"
+                    ></path>
+                </svg>
+            </div>
+            <p>
+                Import and export your Localization strings with embedded metadata into an external TMS system with
+                standardized XLIFF files.
+            </p>
+
+            <div className="button-stack">
+                <button type="button" onClick={importXliff}>
+                    Import {selectedLocale?.name}
+                </button>
+
+                <button
+                    type="button"
+                    className="framer-button-primary"
+                    onClick={handleExport}
+                    disabled={!selectedLocaleId}
+                >
+                    Export {selectedLocale?.name}
+                </button>
+            </div>
+        </main>
+    )
+}
diff --git a/plugins/localization-import-export/src/assert.ts b/plugins/localization-import-export/src/assert.ts
@@ -0,0 +1,8 @@
+/**
+ * A utility function that does nothing but makes TypeScript check for the never type.
+ *
+ * For example, sometimes something that should never happen is expected to
+ * happen, like during a rollback. To prevent unwanted crashers use
+ * `shouldBeNever` instead of `assertNever`.
+ */
+export function shouldBeNever(_: never) {}
diff --git a/plugins/localization-import-export/src/files.ts b/plugins/localization-import-export/src/files.ts
@@ -0,0 +1,27 @@
+export function downloadBlob(value: string, filename: string, type: string) {
+    const blob = new Blob([value], { type })
+    const url = URL.createObjectURL(blob)
+
+    const a = document.createElement("a")
+    a.href = url
+    a.download = filename
+
+    a.click()
+    URL.revokeObjectURL(url)
+}
+
+export function importFileAsText(accept: string, handleImport: (file: string) => Promise<void>) {
+    const input = document.createElement("input")
+    input.type = "file"
+    input.accept = accept
+
+    input.onchange = async event => {
+        const file = (event.target as HTMLInputElement).files?.[0]
+        if (!file) return
+        const fileText = await file.text()
+
+        void handleImport(fileText)
+    }
+
+    input.click()
+}
diff --git a/plugins/localization-import-export/src/main.tsx b/plugins/localization-import-export/src/main.tsx
@@ -0,0 +1,14 @@
+import "framer-plugin/framer.css"
+
+import React from "react"
+import ReactDOM from "react-dom/client"
+import { App } from "./App.tsx"
+
+const root = document.getElementById("root")
+if (!root) throw new Error("Root element not found")
+
+ReactDOM.createRoot(root).render(
+    <React.StrictMode>
+        <App />
+    </React.StrictMode>
+)
diff --git a/plugins/localization-import-export/src/vite-env.d.ts b/plugins/localization-import-export/src/vite-env.d.ts
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Localization Import & Export

		Import and export your Framer localizations using the common XLIFF format.