Standardize draft generation terminology

[Nateowami]

This PR updates the Scripture Forge extension to consistently use the term "Generated Drafts" or "Draft Generation" instead of "Auto Drafts" throughout the codebase. This aligns the extension with the terminology Scripture Forge and the teams working with it use. "Auto drafts" was in the Scripture Forge UI in a few places for a short while before we had agreed on terminology, but was never an agreed-upon term.

---

This change is 

[tjcouch-sil]

Hi Nathaniel! Thanks for jumping in and working on this! I have some feedback for you pretty much just around avoiding breaking changes, but it looks good overall!

@tjcouch-sil reviewed 5 files and all commit messages, and made 5 comments.
Reviewable status: all files reviewed, 4 unresolved discussions (waiting on @irahopkinson, @lyonsil, and @Nateowami).

---

src/scripture-forge/src/types/scripture-forge.d.ts line 451 at r1 (raw file):

     * @returns WebView id for new Scripture Forge home WebView or `undefined` if not created
     */
    'scriptureForge.openGeneratedDrafts': () => Promise<string | undefined>;

To avoid breaking changes (e.g. to avoid another extension calling the old name and failing), please deprecate the existing command and make this new command.

---

src/scripture-forge/src/main.ts line 236 at r1 (raw file):

  const openGeneratedDraftsCommandPromise = papi.commands.registerCommand(
    'scriptureForge.openGeneratedDrafts',
    async () => {

To avoid breaking changes as mentioned in the type declaration file, you can register this same function twice for the two different command names.

---

src/scripture-forge/contributions/menus.json line 8 at r1 (raw file):

      {
        "label": "%mainMenu_scriptureForge_openGeneratedDrafts_label%",
        "localizeNotes": "Application main menu > Project > Open Generated Drafts",

I see the casing is different for "Open Generated Drafts" here vs "Open generated drafts" in the localized string. Which one is the expected capitalization? Just double checking that the localized string capitalization is right since it is different in these two places; it's not actually essential for these localizeNotes to have the right capitalization ;)

IIRC UX says to use sentence case for menu items in general, but I dunno if "Generated Drafts" is a proper noun that would warrant title case like I did with "Auto Drafts" before.

---

src/scripture-forge/contributions/localizedStrings.json line 5 at r1 (raw file):

  "localizedStrings": {
    "en": {
      "%mainMenu_scriptureForge_openGeneratedDrafts_label%": "Open draft generation",

Regarding all these localized strings, please deprecate and make new strings instead of changing or renaming existing ones to avoid breaking changes (e.g. another extension using one of these changed strings; unlikely but possible) since this extension has been published and distributed with these strings.

[Nateowami]

Thanks for the review!

@Nateowami made 6 comments.
Reviewable status: 1 of 5 files reviewed, 5 unresolved discussions (waiting on @irahopkinson, @lyonsil, and @tjcouch-sil).

---

src/scripture-forge/contributions/localizedStrings.json line 5 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

Regarding all these localized strings, please deprecate and make new strings instead of changing or renaming existing ones to avoid breaking changes (e.g. another extension using one of these changed strings; unlikely but possible) since this extension has been published and distributed with these strings.

I can't tell from the linked documentation how to deprecate a string. The file has this:

  "%test_deprecated_string%": {
    "deprecationInfo": {
      "date": "2025-04-21",
      "message": "This exists to test deprecating localized strings. Do not remove or use."
    }
  },

I see an object, but not the original string. In this file the format is "key": "string", but there the format seems to be "key": <object> with no string.

---

src/scripture-forge/contributions/menus.json line 8 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

I see the casing is different for "Open Generated Drafts" here vs "Open generated drafts" in the localized string. Which one is the expected capitalization? Just double checking that the localized string capitalization is right since it is different in these two places; it's not actually essential for these localizeNotes to have the right capitalization ;)

IIRC UX says to use sentence case for menu items in general, but I dunno if "Generated Drafts" is a proper noun that would warrant title case like I did with "Auto Drafts" before.

I depends on the application conventions. For the most part I tried to keep the same casing unless I thought it was obviously incorrect. I'll change it.

---

src/scripture-forge/src/main.ts line 236 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

To avoid breaking changes as mentioned in the type declaration file, you can register this same function twice for the two different command names.

Done.

---

src/scripture-forge/src/types/scripture-forge.d.ts line 451 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

To avoid breaking changes (e.g. to avoid another extension calling the old name and failing), please deprecate the existing command and make this new command.

Done.

---

src/scripture-forge/contributions/localizedStrings.json line 10 at r1 (raw file):

      "%project_settings_scriptureForge_projectId_description%": "This project's ID according to Scripture Forge. It is generated upon connecting a project to Scripture Forge. This is distinct from the project's ID according to Paratext. Empty means the project is not connected to Scripture Forge.",
      "%scriptureForge_draft_action_canJoin%": "Join project",
      "%scriptureForge_draft_action_cannotAccessDrafts%": "Ask your administrator for access to generate drafts.",

How do I handle this one? The string should change, but the key still makes sense. Same question for the changes lower in this file.

[tjcouch-sil]

@tjcouch-sil reviewed 4 files and all commit messages, made 5 comments, and resolved 2 discussions.
Reviewable status: all files reviewed, 3 unresolved discussions (waiting on @irahopkinson, @lyonsil, and @Nateowami).

---

src/scripture-forge/contributions/localizedStrings.json line 5 at r1 (raw file):

Previously, Nateowami wrote…

I can't tell from the linked documentation how to deprecate a string. The file has this:

  "%test_deprecated_string%": {
    "deprecationInfo": {
      "date": "2025-04-21",
      "message": "This exists to test deprecating localized strings. Do not remove or use."
    }
  },

I see an object, but not the original string. In this file the format is "key": "string", but there the format seems to be "key": <object> with no string.

Ah, I see; the example linked was from core code, not extension code. Sorry. I updated the example there. Here's the new extension code link for convenience.

---

src/scripture-forge/contributions/localizedStrings.json line 10 at r1 (raw file):

Previously, Nateowami wrote…

How do I handle this one? The string should change, but the key still makes sense. Same question for the changes lower in this file.

However you want :) I think we often just add a _2 to the end, but I don't think we really have a convention.

---

src/scripture-forge/contributions/menus.json line 8 at r1 (raw file):

Previously, Nateowami wrote…

I depends on the application conventions. For the most part I tried to keep the same casing unless I thought it was obviously incorrect. I'll change it.

Gotcha, thanks!

---

src/scripture-forge/src/main.ts line 236 at r1 (raw file):

Previously, Nateowami wrote…

Done.

Thanks!

---

src/scripture-forge/src/types/scripture-forge.d.ts line 451 at r1 (raw file):

Previously, Nateowami wrote…

Done.

Thanks! Sorry; something I didn't think to mention is that we always put the deprecation date on our deprecation messages in addition to the suggestions for how to adapt (like you already put). We intend to support deprecated things for some X amount of time (we haven't decided yet) before removing them, so this makes it easy for us and extension developers to keep track of when something will be removed (at least, once we decide on the deprecation time limit! 😂)

E.g. https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-utils/src/scripture/usj-reader-writer.model.ts#L24

[tjcouch-sil]

Looks good other than one thing to check in on. Thanks! I appreciate your patience with our processes :)

@tjcouch-sil reviewed 3 files and all commit messages, made 2 comments, and resolved 3 discussions.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @irahopkinson, @lyonsil, and @Nateowami).

---

src/scripture-forge/contributions/localizedStrings.json line 43 at r3 (raw file):

      "%scriptureForge_draft_action_canJoin%": "Join project",
      "%scriptureForge_draft_action_cannotAccessDrafts%": "Ask your administrator for access to Auto Drafts.",
      "%scriptureForge_draft_action_cannotAccessDrafts_2%": "Ask your administrator for access to generate drafts.",

These newly changed localized string keys need to have their usage updated, right?

If I missed something, feel free to resolve this and merge :)

[Nateowami]

Coming back to this I'm wondering whether it really makes sense to add new strings instead of changing the existing ones. While I don't think any extension should be referencing these strings, if any did, they should get the new/updated strings, should they not?

@Nateowami made 6 comments.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @irahopkinson, @lyonsil, and @tjcouch-sil).

---

src/scripture-forge/contributions/localizedStrings.json line 5 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

Ah, I see; the example linked was from core code, not extension code. Sorry. I updated the example there. Here's the new extension code link for convenience.

Thanks. Updated.

---

src/scripture-forge/contributions/localizedStrings.json line 10 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

However you want :) I think we often just add a _2 to the end, but I don't think we really have a convention.

Done.

---

src/scripture-forge/contributions/localizedStrings.json line 43 at r3 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

These newly changed localized string keys need to have their usage updated, right?

If I missed something, feel free to resolve this and merge :)

🤦‍♂️ Yes, I forgot to make those changes.

---

src/scripture-forge/contributions/menus.json line 8 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

Gotcha, thanks!

Part of me thinks the menu should really mention Scripture Forge, since that's likely what users will be looking for.

---

src/scripture-forge/src/types/scripture-forge.d.ts line 451 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

Thanks! Sorry; something I didn't think to mention is that we always put the deprecation date on our deprecation messages in addition to the suggestions for how to adapt (like you already put). We intend to support deprecated things for some X amount of time (we haven't decided yet) before removing them, so this makes it easy for us and extension developers to keep track of when something will be removed (at least, once we decide on the deprecation time limit! 😂)

E.g. https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-utils/src/scripture/usj-reader-writer.model.ts#L24

Thanks; adding a date is definitely a good idea. Done.

[tombogle]

I agree. For clarity, you can (and maybe should) add a new key as well and create a fallback key entry. That way any new code will use a key that has the preferred wording. If anyone did use the old key and really wants/needs the test to say Auto Draft (maybe for some totally unrelated reason/feature), then they will be disappointed, but I think the chances of that are incredibly slim!

[tjcouch-sil]

Yes, existing extensions using these same string keys would get the updated English localized string values.

However, there are two problems with updating a string in place:

1. Other uses of the string. If someone were counting on the string saying "Auto drafts" for something they made and then it got changed to "Generated drafts", that's no good; their thing just changed names without their intent. Of course, one might argue they should be making their own strings for their own proper names, but it's still a possibility.
2. Other translations of the string. If someone made a translation extension that translated these strings into French, for example, then all you did was change this string in place, they would not know that they need to translate a new string value. And your stuff would still say whatever the French for "Auto drafts" is :) who knows; maybe they would never realize the difference and would never translate the new value! Then, of course, anyone translating the string from French to something else would also have to figure out the difference and do the translation themselves.
   • Note: this point is why we don't usually list the old deprecated string as a fallback string for the new string with new wording.

In theory, these are significant enough issues to consider these breaking changes that need new strings rather than in-place changes. In practice, who knows? That's why I always suggest we stick to the theory. When people push back enough on this topic when it doesn't matter that much, I give. So do what you think is best with the information presented to you :)

@tjcouch-sil made 3 comments.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on @irahopkinson, @lyonsil, and @Nateowami).

---

src/scripture-forge/contributions/localizedStrings.json line 43 at r3 (raw file):

Previously, Nateowami wrote…

🤦‍♂️ Yes, I forgot to make those changes.

I'm not seeing these changes in implementation yet - I suspect likely because you aren't sure you want to make the changes after all.

---

src/scripture-forge/contributions/menus.json line 8 at r1 (raw file):

Previously, Nateowami wrote…

Part of me thinks the menu should really mention Scripture Forge, since that's likely what users will be looking for.

Seems reasonable to me to say something like "Open Scripture Forge generated drafts", but please talk to Alex as this is a UX topic and is not particularly in my wheelhouse :)

If you don't want to make any changes, feel free to resolve this thread yourself.

[tjcouch-sil]

looks great! Thanks for the persistence with this. Sorry for the slow process.

@tjcouch-sil reviewed 5 files and all commit messages, made 3 comments, and resolved 2 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @irahopkinson and @lyonsil).

---

src/scripture-forge/contributions/localizedStrings.json line 43 at r3 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

I'm not seeing these changes in implementation yet - I suspect likely because you aren't sure you want to make the changes after all.

Looks good! Thanks!

---

src/scripture-forge/contributions/menus.json line 8 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

Seems reasonable to me to say something like "Open Scripture Forge generated drafts", but please talk to Alex as this is a UX topic and is not particularly in my wheelhouse :)

If you don't want to make any changes, feel free to resolve this thread yourself.

I am resolving assuming you talked to Alex about this or feel enough sovereignty that you don't see a need.

[Nateowami]

[sorry, forgot I hadn't posted my comments]

Thanks for the explanation. I would agree with point 2, though I consider that an aspect of the localization strategy. Scripture Forge has a much more centralized localization approach (using Crowdin), which means strings will get updated if you change them. A decentralized approach to translating strings might not offer the same flexibility. That said, I still think an translation tool that doesn't contemplate a string changing is just a flawed translation tool.

I don't really find point 1 compelling; I think if an extension asks for "%mainMenu_scriptureForge_openAutoDrafts_label%, they are explicitly asking for the string that the Scripture Forge extension uses to launch. For example, there might be some text that says You can view drafts by opening the main menu and clicking {{ "%mainMenu_scriptureForge_openAutoDrafts_label% }}. That's the reasonable use-case for referencing another extension's strings. The unreasonable use-case is "I want that exact string and am too lazy to put it in my own extension", and it seems pretty obvious that it's an unreasonable approach when the string is prefixed with the extension name.

On a separate note, I haven't been able to actually test the changes because for a while I couldn't get Paratext 10 to really run well at all (it would launch, but was only somewhat functional). Now it works better, but I can't sign into SF. I think there's an issue with setting up the protocol handler, right? Is there a solution for that?

@Nateowami made 3 comments.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @irahopkinson and @lyonsil).

---

src/scripture-forge/contributions/localizedStrings.json line 43 at r3 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

Looks good! Thanks!

[forgot to post this after pushing updates]
Yes, I held off on pushing those changes.

---

src/scripture-forge/contributions/menus.json line 8 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

I am resolving assuming you talked to Alex about this or feel enough sovereignty that you don't see a need.

[forgot to post this after pushing updates]
I'll talk to Alex. Let's hold off on merging until then.