Content source: auto-translation

docs/integrations/sources/README.md

@@ -0,0 +1,40 @@
+# Content sources 
+
+Integrations can act as sources for computing content from external sources. Use-cases include:
+
+- Translation: auto-translate another content and keeping it updated
+- Changelog
+- Code documentation
+
+
+## Flow
+
+## Create a content source
+
+First of all, content sources should be listed in the `gitbook-manifest.yaml` file, under `sources`:
+
+```yaml
+sources:
+    - id: pirate
+      title: Content as a Pirate
+```
+
+Then the content source can be implemented:
+
+```ts
+import { createContentSource } from '@gitbook/runtime';
+
+const pirate = createContentSource({
+    sourceId: 'pirate',
+    getPages: () => {
+
+    },
+    getPageDocument: () => {
+
+    }
+});
+```
+
+## Refreshing content when source has changed
+
+At the moment, an integration source can only depend on a GitBook space as a dependency. But we plan on implementing supporting for custom dependencies that can be refreshed.

integrations/github-copilot/src/configuration.tsx

@@ -1,22 +1,20 @@
 import { ContentKitIcon } from '@gitbook/api';
-import { createComponent, getOAuthToken } from '@gitbook/runtime';
+import { InstallationConfigurationProps, createComponent, getOAuthToken } from '@gitbook/runtime';
 
 import { fetchGitHubInstallations } from './github';
 import { getGitHubOAuthConfiguration } from './oauth';
-import type { GitHubCopilotConfiguration, GitHubCopilotRuntimeContext } from './types';
+import type {
+    GitHubCopilotConfiguration,
+    GitHubCopilotRuntimeContext,
+    GitHubCopilotRuntimeEnvironment,
+} from './types';
 import { createGitHubSetupState } from './setup';
 
-type ConfigureProps = {
-    installation: {
-        configuration?: GitHubCopilotConfiguration;
-    };
-};
-
 /**
  * ContentKit component to configure the GitHub Copilot integration.
  */
 export const configurationComponent = createComponent<
-    ConfigureProps,
+    InstallationConfigurationProps<GitHubCopilotRuntimeEnvironment>,
     {
         installations: string[];
     },

integrations/openai-translate/gitbook-manifest.yaml

@@ -0,0 +1,31 @@
+name: openai-translate
+title: Translate with OpenAI
+organization: gitbook
+visibility: public
+description: Automatically generate translation content using OpenAI
+icon: ./assets/icon.png
+externalLinks:
+    - label: Documentation
+      url: https://docs.gitbook.com/integrations/github-copilot
+categories:
+    - collaboration
+summary: |
+    # Overview
+
+    Automically generate translations of your content that are kept to date to any changes using OpenAI GPT models.
+
+    # How to use it
+
+    Install the integration on your account and grant access to the source space and the target space.
+script: src/index.ts
+scopes:
+    - space:content:read
+configurations:
+    account:
+        componentId: configure
+contentSources:
+    - id: translate
+      title: Translate with AI
+      description: Generate automatic translation from a space using AI.
+      configuration:
+          componentId: configureSource

integrations/openai-translate/package.json

@@ -0,0 +1,22 @@
+{
+    "name": "@gitbook/integration-openai-translate",
+    "version": "0.0.0",
+    "private": true,
+    "scripts": {
+        "typecheck": "tsc --noEmit",
+        "check": "gitbook check",
+        "publish-integrations": "gitbook publish .",
+        "publish-integrations-staging": "gitbook publish .",
+        "logs": "gitbook tail",
+        "dev": "gitbook dev"
+    },
+    "dependencies": {
+        "@gitbook/api": "*",
+        "@gitbook/runtime": "*",
+        "openai": "^4.67.1"
+    },
+    "devDependencies": {
+        "@gitbook/cli": "workspace:*",
+        "@gitbook/tsconfig": "workspace:*"
+    }
+}

integrations/openai-translate/src/configureComponent.tsx

@@ -0,0 +1,90 @@
+import { createComponent, InstallationConfigurationProps } from '@gitbook/runtime';
+
+import {
+    DEFAULT_MODEL,
+    type OpenAITranslateRuntimeContext,
+    type OpenAITranslateRuntimeEnvironment,
+} from './types';
+
+/**
+ * ContentKit component to configure the integration.
+ */
+export const configureComponent = createComponent<
+    InstallationConfigurationProps<OpenAITranslateRuntimeEnvironment>,
+    {
+        apiKey: string;
+        model: string;
+        apiUrl: string;
+    },
+    { action: 'save' },
+    OpenAITranslateRuntimeContext
+>({
+    componentId: 'configure',
+    initialState: (props, _, context) => {
+        return {
+            apiKey: props.installation.configuration.apiKey ?? '',
+            model: props.installation.configuration.model ?? DEFAULT_MODEL,
+            apiUrl: props.installation.configuration.apiUrl ?? '',
+        };
+    },
+    action: async (element, action, ctx) => {
+        const { integration, installation } = ctx.environment;
+        if (action.action === 'save' && installation) {
+            await ctx.api.integrations.updateIntegrationInstallation(
+                integration.name,
+                installation.id,
+                {
+                    configuration: {
+                        apiKey: element.state.apiKey,
+                        model: element.state.model,
+                        apiUrl: element.state.apiUrl,
+                    },
+                },
+            );
+        }
+
+        return element;
+    },
+    render: async (element, context) => {
+        return (
+            <block>
+                <input
+                    label="API Key"
+                    hint="OpenAI API key"
+                    element={<textinput state="apiKey" />}
+                />
+                <input
+                    label="API URL"
+                    hint="When using a custom provider or proxy, enter the URL of the OpenAI API."
+                    element={<textinput state="apiUrl" />}
+                />
+                <input
+                    label="Model"
+                    hint="Select the model to use for translation. We recommend picking powerful models like GPT-4 or GPT-4o."
+                    element={
+                        <select
+                            state="model"
+                            options={[
+                                {
+                                    id: 'gpt-4',
+                                    label: 'GPT-4',
+                                },
+                                {
+                                    id: 'gpt-4o',
+                                    label: 'GPT-4o',
+                                },
+                            ]}
+                        />
+                    }
+                />
+                <button
+                    style="primary"
+                    label="Save"
+                    onPress={{
+                        action: 'save',
+                    }}
+                />
+            </block>
+        );
+    },
+});

integrations/openai-translate/src/configureSourceComponent.tsx

@@ -0,0 +1,94 @@
+import { createComponent } from '@gitbook/runtime';
+
+import type { OpenAITranslateRuntimeContext } from './types';
+
+/**
+ * ContentKit component to configure the Translation source.
+ */
+export const configureSourceComponent = createComponent<
+    {},
+    {
+        space?: string;
+        language: string;
+    },
+    void,
+    OpenAITranslateRuntimeContext
+>({
+    componentId: 'configureSource',
+    initialState: (props, _, context) => {
+        return {
+            language: 'en',
+        };
+    },
+    render: async (element, context) => {
+        const { api, environment } = context;
+        const { integration, installation } = environment;
+
+        if (!installation) {
+            throw new Error('Installation not found');
+        }
+
+        const {
+            data: { items: spaces },
+        } = await api.integrations.listIntegrationInstallationSpaces(
+            integration.name,
+            installation.id,
+        );
+        return (
+            <block>
+                <input
+                    label="Source space"
+                    hint="Select the space to translate content from."
+                    element={
+                        <select
+                            state="space"
+                            options={spaces.map((space) => ({
+                                id: space.space,
+                                label: space.space,
+                            }))}
+                        />
+                    }
+                />
+                <input
+                    label="Language"
+                    hint="Select the language to translate content to."
+                    element={
+                        <select
+                            state="language"
+                            options={[
+                                { label: 'English', id: 'en' },
+                                { label: 'French', id: 'fr' },
+                                { label: 'German', id: 'de' },
+                                { label: 'Italian', id: 'it' },
+                                { label: 'Japanese', id: 'ja' },
+                                { label: 'Korean', id: 'ko' },
+                                { label: 'Portuguese', id: 'pt' },
+                                { label: 'Russian', id: 'ru' },
+                                { label: 'Spanish', id: 'es' },
+                            ]}
+                        />
+                    }
+                />
+                <button
+                    style="primary"
+                    label="Continue"
+                    onPress={{
+                        action: '@ui.submit',
+                        returnValue: {
+                            props: {
+                                space: element.dynamicState('space'),
+                                language: element.dynamicState('language'),
+                            },
+                            dependsOn: [
+                                {
+                                    kind: 'space',
+                                    space: element.dynamicState('space'),
+                                },
+                            ],
+                        },
+                    }}
+                />
+            </block>
+        );
+    },
+});

integrations/openai-translate/src/index.ts

@@ -0,0 +1,9 @@
+import { createIntegration } from '@gitbook/runtime';
+import { translateContentSource } from './translateContentSource';
+import { configureComponent } from './configureComponent';
+import { configureSourceComponent } from './configureSourceComponent';
+
+export default createIntegration({
+    contentSources: [translateContentSource],
+    components: [configureComponent, configureSourceComponent],
+});

integrations/openai-translate/src/openai.ts

@@ -0,0 +1,58 @@
+import { OpenAI } from 'openai';
+import { OpenAITranslateRuntimeContext } from './types';
+import { ExposableError } from '@gitbook/runtime';
+
+/**
+ * Get the OpenAI client associated with the current runtime context.
+ */
+export function getOpenAI(ctx: OpenAITranslateRuntimeContext): OpenAI {
+    const apiKey = ctx.environment.installation?.configuration.apiKey;
+    if (!apiKey) {
+        throw new ExposableError('OpenAI API key is missing');
+    }
+    return new OpenAI({
+        apiKey,
+        baseURL: ctx.environment.installation?.configuration.apiUrl,
+    });
+}
+
+/**
+ * Translate a JSON object using OpenAI, by indicating the properties that can be translated.
+ */
+export async function translateJSON<T>(
+    ctx: OpenAITranslateRuntimeContext,
+    language: string,
+    object: T,
+    properties: string[],
+): Promise<T> {
+    const openai = getOpenAI(ctx);
+    const result = await openai.chat.completions.create({
+        model: ctx.environment.installation?.configuration.model ?? 'gpt-4o',
+        messages: [
+            {
+                role: 'system',
+                content: [
+                    'You are an AI that can translate JSON input, a powerful language model designed for seamless translation of text across multiple languages.',
+                    `You excel at generating structured data in JSON format and follow this rules: you never translate the key, you always use the double quotes to surround key and value, you always escape single quotes and backslashes contained in the value, you never write a comma at the end of the last row in the file.`,
+                    `Translate the following JSON input into ${language} while preserving its structure. Only the properties ${properties.map((prop) => JSON.stringify(prop)).join(', ')}, can be translated and will be modified.`,
+                ].join('\n'),
+            },
+            {
+                role: 'user',
+                content: JSON.stringify({
+                    input: object,
+                }),
+            },
+        ],
+        response_format: {
+            type: 'json_object',
+        },
+    });
+
+    try {
+        const translated = JSON.parse(result.choices[0].message.content!);
+        return translated.input;
+    } catch (error) {
+        throw new ExposableError('Failed to translate content: ' + (error as Error).message);
+    }
+}