better naming/organization of settings, options, and appSpecificApi

[samuelstroschein]

From #1221 (comment)

I currently use addAppSpecificApi to set settings for the SDK. I think it could be confusing if we introduce two different concepts on how to configure applications.

There is confusion indeed. Let's try to come up with better names.

Context

• appSpecificApi is supposed to be used as "app-specific plugin". API usage looks as follows inlang.plugin.appSpecificApi.
• settings are user defined settings
• options are configuration options for plugins and lint rules

Observation

• The main confusion seems to stem from nesting options in settings.
• The sdk-js might have been a bad example for settings.apps. The ide extension however is a good example. For example, whether the ide extension should activate is unrelated to plugins (settings) settings.app['inlang.ide-extension'].activate. Or, how telemetry works settings.app['inlang.sdk-js'].telemetry === "off".

[samuelstroschein]

Problem

• What are options?
• What are settings?
• What is passed to plugins, lint rules, and apps?

Proposal

https://www.loom.com/share/f1c48c10cddf41aa96e1767b74bf2ef5

• Change the inlang config to contain only settings
• settings are always passed in full to the corresponding identified app, lint rule, or plugin
• system is a reserved namespace for "system wide settings" like a lint level overwrite

The config is inspired by VSCode's settings which also only consist of key-value pairs and seem to make our communication and internal logic easier.

// inlang.config.json
{
	"sourceLanguageTag": "en",
	"languageTags": ["en"],
	"modules": ["./dist/index.js"],
	"settings": {
	         // system wide settings
		"system": {
			"lintRuleLevels": {
				"inlang.lint-rule-missing-message": "error",
				"inlang.lint-rule-missing-pattern": "off"
			}
		},
		"inlang.ide-extension": {
			"activate": false
		},
		"inlang.sdk-js": {
			"telemetry": "off"
		},
		"inlang.lint-rule-missing-message": {
			"ignore": ["*inlang|globalization"]
		},
		"inlang.plugin-i18next": {
			"pathPattern": "./examples/example01/{languageTag}.json",
			"variableReferencePattern": ["{", "}"]
		}
	}
}

Pros

• very simple "settings are key-value pairs" concept
• removal of the options concept
• simplified business logic "your plugin/lint rule receives the settings that correspond to the id" logic instead of "your plugin/lint rule receives the options defined in settings for the corresponding id"

Cons

• duplication of ids e.g. settings['inlang.rule-missing-message'] and settings.global.lintRuleLevels['inlang.rule-missing-message'] but this is mostly handled inside of @inlang/app anyways

[samuelstroschein]

Follow up question, should we enforce naming of plugins and lint rules with namespace.plugin-* and namespace.lint-rule-* respectively?

Vote with 👍 or 👎 if plugin und rule naming should be enforced in this comment.

[samuelstroschein]

@inlang/team

[ivanhofer]

But how does it solve this?

[samuelstroschein]

Your current approach works via addAppSpecificApis works and seems OK. After all, appSpecificApi exists for apps to do whatever they need.

From an internal perspective, it seems like we have sdk-js is a plugin on it's own. For each framework/metaframework a plugin that extends sdk-js exists. Forget the global app config, I think defining settings via plugins makes indeed more sense!

// inlang/sdk-js
type SdkJsSettings = {
  telemetry: "on" | "off"
}

// inlang/sdk-js-{framework}
type SdkJsReactSettings = SdkJsSettings & {
  svelteIsBetter: true
}

// inlang/sdk-js-{metaframework}
type SdkJsNextJsSettings = SdkJsSettings & {
  languageNegotation: "localStorage" | "cookie"
}

// inlang.config.json
{
	"settings": {
		"inlang.plugin-sdk-js": {
			"telemetry": "off",
		},
	}
}

{
	"settings": {
		"inlang.plugin-sdk-js-react": {
			"svelteIsBetter": true
		},
	}
}

{
	"settings": {
		"inlang.plugin-sdk-js-nextjs": {
			"telemetry": "on",
			"languageNegotation": "localStorage"
		},
	}
}

[NilsJacobsen]

I think that makes sense. I also was confused by settings and options at some point. As long as the module resolver can easily work with that I vote for changing it. 👍