official plugin API

[ivanhofer]

Problem

Defining readResources and writeResources is a bit boilerplaty.

Proposal

Change it from this:

/**
 * @type {import("@inlang/core/config").DefineConfig}
 */
export async function defineConfig(env) {
  const plugin = await env.$import(
    "https://cdn.jsdelivr.net/gh/ivanhofer/inlang-plugin-typesafe-i18n/dist/index.js"
  )

  return {
    referenceLanguage: 'en',
    languages: ['en', 'de'],
    readResources: (args) =>
      plugin.readResources({ ...args, ...env }),
    writeResources: (args) =>
      plugin.writeResources({ ...args, ...env }),
  }
}

to this:

/**
 * @type {import("@inlang/core/config").DefineConfig}
 */
export async function defineConfig(env) {
  const plugin = await env.$import(
    "https://cdn.jsdelivr.net/gh/ivanhofer/inlang-plugin-typesafe-i18n/dist/index.js"
  )

  return {
    referenceLanguage: 'en',
    languages: ['en', 'de'],
    plugin: plugin(/* optional configuration of plugin */),
}

Additional information

This would be a breaking change, because the export of the plugin would slightly change.

export default plugin = (config: PluginOptions) => {
	
	// do some initialization steps

	return {
		readResources: ({ $fs, $import }) => /* implementation */,
		writeResources: ({ $fs, $import }) => /* implementation */,
	}
}

This could open up the possibility for the plugin to provide useful information e.g. a library knows best what locales are set up in that repo. Currently you would need to mange two list of supported locales. One for the library and one for the inlang config.

For typesafe-i18n I have done it like this:

/**
 * @type {import("@inlang/core/config").DefineConfig}
 */
export async function defineConfig(env) {
  /**
   * @type {import("typesafe-i18n/config")}
   */
  const { getLocaleInformation } = await env.$import("https://cdn.jsdelivr.net/npm/[email protected]/config/index.mjs")

  // initialize the plugin
  const plugin = await env.$import(
    "https://cdn.jsdelivr.net/gh/ivanhofer/inlang-plugin-typesafe-i18n/dist/index.js"
  )

  // get the locale information from `typesafe-i18n`
  const { base, locales } = await getLocaleInformation(env.$fs)

  return {
    referenceLanguage: base,
    languages: locales,
    readResources: (args) =>
      plugin.readResources({ ...args, ...env }),
    writeResources: (args) =>
      plugin.writeResources({ ...args, ...env }),
  }
}

But the plugin could also return referenceLanguage and languages so the config could change to:

/**
 * @type {import("@inlang/core/config").DefineConfig}
 */
export async function defineConfig(env) {
  const plugin = await env.$import(
    "https://cdn.jsdelivr.net/gh/ivanhofer/inlang-plugin-typesafe-i18n/dist/index.js"
  )

  return {
	plugin: plugin()
  }
}

The current downside of this is, that someone is not able to modify the behaviour of the plugin, but inlang could provide hooks for that. e.g. onAfterWriteResources etc.

[samuelstroschein]

The plugin API is purposely non-existent right now. I intend to collect feedback, like this issue, to design a plugin API that covers use cases that we might not foresee right now.

This would be a breaking change, because the export of the plugin would slightly change.

I believe that you are referring to the plugin template. This would not be a breaking change for inlang. As plugin owner, you are (for now) free to choose whatever API you'd like. Granted, that will lead to plugins likely having different configuration APIs but gives inlang the possibility to "nail" an official plugin API based on best practices/different use cases that emerge from plugins.

So keep the feedback coming!

[samuelstroschein]

@ivanhofer

This could open up the possibility for the plugin to provide useful information e.g. a library knows best what locales are set up in that repo. Currently you would need to mange two list of supported locales. One for the library and one for the inlang config.

You could do the following for typesafe-i18n:

/**
 * @type {import("@inlang/core/config").DefineConfig}
 */
export async function defineConfig(env) {
  const typesafeI18nPlugin = await env.$import(
    "https://cdn.jsdelivr.net/gh/ivanhofer/inlang-plugin-typesafe-i18n/dist/index.js"
  )

  // default export or named export. named export seems clearer to me
  const pluginConfig = typesafeI18nPlugin.defineConfig({ // your plugin config })

  return pluginConfig

But, that approach will fail once the user needs/wants to define custom properties. Merging objects with functions is not possible without external libs.

Another alternative could be wrapping the config like so:

/**
 * @type {import("@inlang/core/config").DefineConfig}
 */
export async function defineConfig(env) {
  const typesafeI18nPlugin = await env.$import(
    "https://cdn.jsdelivr.net/gh/ivanhofer/inlang-plugin-typesafe-i18n/dist/index.js"
  )

  // default export or named export. named export seems clearer to me
  const withTypesafeI18n = typesafeI18nPlugin.defineConfig({ // your plugin config })

  return withTypesafeI18n({ 
     // custom config
  })

[samuelstroschein]

Actually, the latter with wrapping seems like a good approach because plugins can be nested without an official plugin API.

/**
 * @type {import("@inlang/core/config").DefineConfig}
 */
export async function defineConfig(env) {
  const plugin1 = await env.$import(
    "https://cdn.jsdelivr.net/gh/ivanhofer/inlang-plugin-typesafe-i18n/dist/index.js"
  )
  const plugin2 = await env.$import(
    "https://cdn.jsdelivr.net/gh/ivanhofer/some-other-plugin/dist/index.js"
  )
  const withPlugin1 = plugin1.defineConfig(// plugin config)
  const withPlugin2 = plugin2.defineConfig(// plugin config)


  return withPlugin2(withPlugin1({ 
     referenceLanguage: "en"
  }))

[samuelstroschein]

@ivanhofer what are your thoughts on this API?

Wouldn't require an official plugin API for now and definitely leads to less boilerplate. Plugins are free to change the config passed from the plugin before.

[ivanhofer]

I find wrapping it a bit odd. Maybe an array makes more sense:

/**
 * @type {import(["@inlang/core/config"](https://www.npmjs.com/package/@inlang/core)).DefineConfig}
 */
export async function defineConfig(env) {
  const plugin1 = await env.$import(
    ["https://cdn.jsdelivr.net/gh/ivanhofer/inlang-plugin-typesafe-i18n/dist/index.js"](https://cdn.jsdelivr.net/gh/ivanhofer/inlang-plugin-typesafe-i18n/dist/index.js)
  )
  const plugin2 = await env.$import(
    ["https://cdn.jsdelivr.net/gh/ivanhofer/some-other-plugin/dist/index.js"](https://cdn.jsdelivr.net/gh/ivanhofer/some-other-plugin/dist/index.js)
  )

  return { 
     plugins: [
        plugin1(/* plugin config */),
        plugin2(/* plugin config */)
    ]
  }
}

Plugin 1 can override the default config and plugin 2 can override/modify/extend things that are returned by plugin 1.
Seems a bit odd at first, but I don't think you will configure multiple plugins that will return the languages-array. You will probably end up with a library-plugin that does this and another plugin that does something else. Here you could also come up with a new term for "library-plugins" where only one is allowed and have the methods of the current plugin system. An use the plugins-array for other stuff, that will eventually require other methods/hooks.

[samuelstroschein]

Hm, your proposal requires an official plugin API and logic. Besides a tiny bit nicer syntax, there seems to be no benefit as both approaches allow plugins to modify the config of the previously returned plugin/initial config?

I thought that the wrapping could be an intermediary solution that requires no official plugin support until requirements from plugin authors are clear.

[ivanhofer]

Didn't fully read your second sentence before ^^
Yes, for now wrapping it like in your example could be an option 👍

[ivanhofer]

I'll try to make the typesafe-i18n plugin more ergonomic. Let's see how it looks at the end.

But I think it would be best if all plugins would have the same API at the end. Makes developing new plugins easier and switching between plugins will be really easy.

[samuelstroschein]

Yep, agree. I am just holding back for a moment to see how people write plugins/what API's they need before an official plugin API is implemented.

[samuelstroschein]

Implemented :)