compile aliases as deprecated in paraglide js

[samuelstroschein]

Problem

Aliases in the context of paraglide JS make little sense.

Aliases have several limitations (https://github.com/opral/monorepo/pull/2198#issuecomment-1934372097) and are only introduced to allow software projects with existing message keys to adopt the inlang ecosystem. Inlang discourages new projects and new messages from using aliases.

Proposal

Guide Paraglide JS users not to use aliases.

Paraglide JS is uniquely positioned as a "day 1" solution (brand new project/first time using messages in code). The need for aliases, which are meant for existing projects, should not exist.

Current idea

Compile aliased messages with a JSDoc @deprecated tag.

• developers will be nudged by the IDE to replace the alias reference with a reference to the message ID
• low friction; incrementally adoptable

Tasks

• [ ] add jsdoc @deprecated comment for aliased messages
• [ ] add diff in comment to give clear instructions on how to change the message reference (m.alias() -> m.id())

Additional information

@LorisSigrist, here is my test comment

/**
 * Change the reference from the alias `m.footer_category_title()` to `m.grumpy_flying_unicorn()`:
 *
 * ```diff
 * - m.footer_category_title()
 * + m.grumpy_flying_unicorn()
 * ```
 *
 * ---
 *
 * `footer_category_title` is an alias for the message `grumpy_flying_unicorn`.
 * Referencing aliases instead of the message ID has severe downsides like:
 *
 * - The alias might be renamed in the future, breaking the code.
 * - Constant naming convention discussions.
 *
 * Read more about aliases and their downsides here inlang.com/link.
 *
 * ---
 *
 * @deprecated reference the message by id `m.grumpy_flying_unicorn()` instead
 *
 * @param {{}} params
 * @param {{ languageTag?: "de" | "en" | "fr" | "it" | "pt-BR" | "sk" | "zh" }} options
 * @returns {string}
 */
/* @__NO_SIDE_EFFECTS__ */
export const footer_category_title

</details>

[samuelstroschein]

@NilsJacobsen I am curious about your thoughts on this proposal as a paraglide js user

[NilsJacobsen]

I like the proposal:

• paraglide is mostly day 1 so i agree
• it makes sense to give paraglide users that already implemented keys the chance to incrementally update
• is there a good way to update my deprecated keys in code? Is there a auto resolve possible? Or a ide-extension helper? If it is a lot of work I will probably ignore the warning.

[LorisSigrist]

Can we close this or should it remain open until #2108 is merged?

[samuelstroschein]

@LorisSigrist lets wait for #2108 to be merged