Feature Suggestion: setting the default language to be the current language specified in the `text` function

[danielFHcode]

In the README file, one of the planned features is said to be:

• Adding set and get method to set default language for a whole document

But typst already has a way of globally (or locally) getting and setting the language for the document - the lang field of the text function (see docs).

So what if we just set the default language to be context text.lang?:

#set text(lang: "en")
#day-name(1) // monday

#set text(lang: "fr")
#day-name(1) // lundi

This would be a breaking change, but seeing as how most people who use a date in a specific language, also probably write the rest of the text in that language, and also considering that this package is not at version 1 yet, I don't think this is much of an issue.

It seams like a pretty elegant solution to me, but even if another way of setting the default is chosen, I think that at least the default of the default should be the language specified in the text function.

[Jeomhps]

Hey, back when I originally coded this project, I aimed for this behavior, which explains its current design. At the time, I couldn't find the text.lang attribute you mentioned, which is why I kinda created my own default attribute. You're absolutely right, though—it would be great to use the text attribute's default language for dates. This would still allow for custom date formats by passing a specific language code. I'll explore this, but it may require updating some assertions. It aligns nicely with the established default behavior.

Also if we use that text.lang as our default language, we could probably just get rid of the config.typ file which contains the default-date-lang variable, and then we would just update the 7th line (lang variable) of the formats.typ to be text.lang then.

datify/src/formats.typ

Line 7 in 8b6d0bc

let lang = default-date-lang

What do you think about this ?

[danielFHcode]

Do notice that if you just set the default language to be text.lang that might cause issues for people who use languages that aren't supported yet, so you'll also need to check whether or not the language is supported and default to English otherwise. I think this logic will probably fit best in the utilities file.
Also notice that the language might change for different parts of the file. I'm not fully sure how context works in relation to functions and variables in typst, though, so it does need some looking into.

[Jeomhps]

So what you are suggesting is create some sort of list to keep track of the supported language and if the text.lang defined language isn't in the supported language list we then default to English but if we are in the case where it is supported we just refer to text.lang then. Yes I think you can set text.lang to different value later inside of one document. I'm not sure how context work aswell, I'm going to document myself on it when I do have a little bit of spare time. That is something I wish to implement.

[Jeomhps]

Hi,

I wanted to follow up with a few updates. I've tried using context text.lang as the default language, but I've encountered an issue. With the way the package is currently coded, making this change causes problems. You can see an example in the screenshot below:

As noted in the documentation, context returns a content type. This creates a conflict because I'm trying to retrieve the name of the day using .at on the dictionary returned by the TOML file. However, .at expects a string, and the fact that context returns content leads to a failure.

I attempted to convert the content back to a string but was unsuccessful. Perhaps there’s a method I’m not aware of? I also tried using text.lang directly, but it absolutely requires a known context.

For now, I’ll need to explore some workarounds to make this functionality possible.

[danielFHcode]

Hi, I just recently remembered this thread and wanted to add some things:

Any time you wrap something with context it makes the type of that thing be content:

#let x = 1
#assert(type(x) == int) // ✅
#let y = context 1
#assert(type(y) == content) // ✅
#assert(type(y) == int) // ❌

This is why you got an error, by wrapping text.lang with context you turned it into a piece of content, which then meant you couldn't use it as a string. The solution would be one of two things:

• You could require that every time someone calls your function they'd have to wrap it with context:

  #let custom-date-format = (date, format, ..args) => {
    // Default values
    let lang = text.lang
    ...
  }
  #context custom-date-format(datetime.today(), "DD-MM-YYYY") // it works!

  But that doesn't seem right, because if someone manually passes in a language this function should not need context at all. You can fix that by only using context when no argument is passed in:

  #let custom-date-format = (date, format, ..args) => {
    // Default values
    let lang = none
  
    // Process variable arguments to extract lang
    for arg in args.pos() {
      if type(arg) == str {
        lang = arg
      }
    }
  
    // Default to text.lang in case no language
    // was provided, which would then require
    // you to use `context`
    if lang == none {
      lang = text.lang
    }
    ...
  }
  
  #custom-date-format(datetime.today(), "DD-MM-YYYY", "en") // ok
  #context custom-date-format(datetime.today(), "DD-MM-YYYY") // ok
  #custom-date-format(datetime.today(), "DD-MM-YYYY") // error

  But this is still not ideal because it would require users of the library to deal with context when it's not really clear why.

• The other solution is to wrap the entire function body with context:

   #let custom-date-format = (date, format, ..args) => context {
     // Default values
     let lang = text.lang
     ...
   }
   #custom-date-format(datetime.today(), "DD-MM-YYYY") // it works!

  The problem with that is that the return type of the function has now been changed from str to content, which means the output cannot be used in any string-related operations (trying to run repr in order to convert the result into a string also doesn't work because repr always returns "context()" when run on things wrapped with content).

I would also like to point out that the original plan for defaults was to add set and get options for the default language, which would require the use of state - which also requires the use of context when retrieving a value. This means that no matter what option is chosen, the default system would inevitably run into the issues mentioned above.

At the end of the day both options aren't ideal and will cause a breaking change, and I don't really think one is that much better or worse than the other. What do you think @Jeomhps?

Off course there is also always the option to not supply a default option and just let people set the default themselves using function.with. Though, on a side note, the way the function is currently set up, the language parameter is a positional argument which means you can't actually set a default using with.

[Jeomhps]

Hi,

Unfortunately, if that would cause a breaking change, I'm not sure how we could manage that. To my surprise, there are a few packages that use mine, and introducing a breaking change might affect their packages as well. If we proceed, we should thoroughly inform them.

On the other hand, the 'function.with' idea might be worth exploring, but would that also bring a breaking change? Additionally, the function would need a significant rework, right? What are your thoughts on all of this?

Is the goal of using the default language set for the document still attainable, or is there no way we can achieve this without introducing some breaking change, which would then lead to the issue you've pointed out?

[danielFHcode]

I don't think breaking changes should be ruled out completely - the way typst imports work makes it so that you have to manually switch to the newer version, so making a minor/major release where the breaking changes are clearly outlined in the docs doesn't seem like such a controversial decision to me.

However, I do personally agree with you that causing a breaking change for something so small will probably cause unnecessary havoc. It's a shame programmatically triggered warnings are not yet done being implemented (though it doesn't seem like anyone's still working on them, to be honest), because then it would be possible to warn about and deprecate certain features before creating an outright breaking change.

You could maybe make it so that people have to opt-in to using the auto-detect-language feature:

#let custom-date-format = (date, format, ..args) => {
  // Default values
  let lang = default-date-lang

  // Process variable arguments to extract lang
  for arg in args.pos() {
    if type(arg) == str {
      lang = arg
    } else if arg == auto {
      lang = text.lang
    }
  }
  ...
}

// when no language is specified it defaults to english - no need for context
#custom-date-format(datetime.today(), "DD-MM-YYYY") // ok
// when a language is specified it uses that language - no need for context
#custom-date-format(datetime.today(), "DD-MM-YYYY", "en") // ok
// when auto is specified it uses `text.lang` - need for context
#context custom-date-format(datetime.today(), "DD-MM-YYYY", auto) // ok
#custom-date-format(datetime.today(), "DD-MM-YYYY", auto) // error

Again, it's not ideal but it works.

As for function.with, this shouldn't require more than changing a couple lines, and I do believe this is a change worth making so that in the future you could support additional parameters such as region (as suggested here). I should note there is a way to support receiving this argument both positionally and namely so that you don't create a breaking change, like so:

#let custom-date-format = (date, format, lang: default-date-lang, ..args) => {
  // Default values
  let lang = lang

  // Process variable arguments to extract lang
  for arg in args.pos() {
    if type(arg) == str {
      lang = arg
    }
  }
  ...
}

But I believe this should be more of a temporary fix before just making a breaking change - maybe a change for 1.0?

It's up to you whether you want to keep positional arguments in or not in the long term. Again, if programmatically triggered warning existed it would be easier to deprecate this feature before removing it, but you could also just add in a helpful panic that pops up after you've introduced the breaking change that says something along the lines of "Passing lang as a positional argument is no longer supported, pass it in a named argument instead, like so: custom-date-format(datetime.today(), "DD-MM-YYYY", lang: "en")" whenever you try to pass a positional argument.

[Jeomhps]

Hi,

From what you're saying, if we use the auto-detect language feature, it should work the same way it does now, but when using auto, we need context. This might work, but I'm not sure if it's the best approach because the user would have to type "auto" every time, which is similar to typing the language itself.

It seems like, in the end, if we want to support the option of falling back on the default language, we have three choices based on your message:

1. Use the default-date-lang and let the user handle the context, but I agree that this seems a bit odd.
2. Put the entire function body in context.
3. Use function.with so the user can provide a default language, but we would need to change the language to be a named argument. You also mentioned that we could add support for the region argument.

Considering these options, I think the third one is the most interesting. However, I'm wondering what Typst is trying to achieve. I think Typst is more focused on context rather than strings, which is how I initially coded the package (which might be the wrong way to do it). As you said, function.with would work and wouldn't change the package much—it would just turn the language parameter into a named argument instead of a positional one. But in the end, I think the function I coded doesn't really follow the philosophy that Typst is trying to achieve. So, maybe it's worth making a bigger change to turn my function into context and add the new region argument you mentioned. What do you think?

[Jeomhps]

To highlight what I want to say about Typst's philosophy focusing on content, take, for instance, the text functions or other functions provided by Typst. These functions prefer taking content as an argument rather than anything else. For example, in their tutorial (Typst Tutorial), the text function is used like this:

#text(font: "New Computer Modern")[
  = Background
  In the case of glaciers, fluid
  dynamics principles can be used
  to understand how the movement
  and behavior of the ice is
  influenced by factors such as
  temperature, pressure, and the
  presence of other fluids (such as
  water).
]

This function manipulates content, and other functions, like the image function, insert content to reuse their terms. So, perhaps I misunderstood this philosophy when I first coded this package. Making the change to focus on content might be worth it to better align with the project's philosophy, which tends toward having most things be content. Secondly, it would help the package evolve in the right direction, allowing us to implement new features in the future.

[danielFHcode]

I'm not sure if I 100% agree with the idea that typst is focused on content. There are a lot of functions in typst that deal with content, but there are also a lot that deal with the other datatypes - such as all of the array methods, or everything in the calc module. While content is obviously the most common datatype you see - because it's basically the type of your entire document - I don't think that the typst philosophy necessarily dictates that you should focus all of your functions on dealing with content, but rather that it just use the most sensible types for the job. The built in datetime.display function does return a string, which seams sensible for their use case, though they didn't have to deal with localization like this library does so I don't know if it's that relevant.

It's also probabeley worth noting that if you're gonna change the default of custom-date-format you probably also want to change the defaults for day-name and month-name to match. This means that if you choose to use context and make custom-date-format return content, day-name and month-name will also have to return content, and so because the custom-date-format uses day-name and month-name internally you would have to overhaul the implementation of custom-date-format.

In general I think the problem here is this library serves 2 purposes:

1. A way to format dates - which seems to be your original goal. People who use this library in this way generally wouldn't really be that impacted by making this function return a piece of content, because that's basically how they're already using it.
2. An API for retrieving the localized name of a the day of the week and the month - I don't know if this was your intention, but this library can actually also serve as a great base for other localization libraries as it hosts an increasingly growing database of translations. Changing the return type of these function(s) makes this side of the library way less useful, because you can no longer manipulate and inspect the data returned by the API - as you did yourself when using functions like first-letter-to-upper and safe-slice to add different formatting capabilities in custom-date-format.

I'm not really sure what's the best way to deal with this issue, but I should note that you don't have to deal with it if you keep the function's current return type.

[Jeomhps]

Hi, thanks for your thoughts. At first, I just wanted to make Typst display function show dates in different languages, not just English. This turned into a tool that also helps with getting names of days and months in different languages since it was needed for my custom-date-format function.

You're right that changing how some functions work could make them less useful for some people, since manipulating context is hard as you mentioned. So, we can keep the current functions for those who need the raw data.

But what if we added new functions that would retrieve the content of the YAML in a context-friendly format? This way, we could create a new function that displays dates contextually. I'm not sure if it's a good idea architecturally, since this could cause confusion. What are your thoughts on this?

[danielFHcode]

I'm not sure what you mean 'context-friendly format', do you mean making a separate version of each function that is the same except it uses context for the lang parameter? Because that seems a bit overengineered.

[Jeomhps]

Hey @danielFHcode,

Long time no see! I’ve been thinking again about what you said in this issue. You were right: there are really two things in this package—the API and the Datify functions. I still haven’t found a solution to the original issue, but as Typst evolves, maybe it’ll get easier to address.

In the meantime, I think separating the API into its own package could be a step forward. That way, Datify would just depend on it, and people could use the API on its own if they want. For Datify users, nothing would change, but the project would be more defined, clearer, and maybe even help with this issue in the future.

I’d also update the README to explain where to contribute for each part.

Does that sound like a good move to you?

Thank you for your insights !