view release on metacpan or  search on metacpan

lib/Apache2/API/Headers/AcceptLanguage.pm  view on Meta::CPAN

Returns the best matching L<locale|Locale::Unicode> from the provided list of supported locales.

It returns an empty string if nothing matched, or sets an L<error|Module::Generic/error> and returns C<undef> in scalar context, or returns an empty list in list context.

=head2 preferences

Read-only.

Returns an array reference of locales, submitted by the user C<Accept-Language> header in his HTTP request, sorted by decreasing quality, with duplicates removed (keeping highest C<q>).

If an error occurred, it sets an error that can be retrieved with the L<error method|Module::Generic/error>, and it returns C<undef> in scalar context, or an empty list in list context.

=head1 EXAMPLES

=head2 1. Exact beats primary language at same q

    my $al = Apache2::API::Headers::AcceptLanguage->new('fr-FR;q=0.9, fr;q=0.9');
    $al->match([ 'fr-CA', 'fr-FR' ]);
    # "fr-FR"

=head2 2. Primary language matches a more specific server locale

    my $al = Apache2::API::Headers::AcceptLanguage->new('en;q=0.9, fr;q=0.8');
    $al->match([ 'fr-FR', 'en-GB' ]);
    # "en-GB"

=head2 3. Wildcard at higher q picks first supported

    my $al = Apache2::API::Headers::AcceptLanguage->new('*;q=1.0, en;q=0.9');
    $al->match([ 'fr-FR', 'en-GB' ]);
    # "fr-FR"

=head1 LEGACY MATCH PRIORITY

Set C<$Apache2::API::Headers::AcceptLanguage::MATCH_PRIORITY_0_01_STYLE> to true to apply “offer order” tie-breaking within equal-C<q> buckets (see L<Apache2::API::Headers::AcceptCommon/"MATCH PRIORITY MODE"> for details).

=head1 NOTES ON TAGS

Tags are parsed using L<Locale::Unicode>. Invalid tags are discarded. For robust behavior, pass your supported locales in the same syntax you intend to serve, such as C<en>, C<en-GB>, C<ja-JP>.

=head1 PERFORMANCE

The matchers called with L<Apache2::API::Headers::AcceptCommon/match> loops through the array reference of supported locales times the number of parsed acceptable locales as submitted by the client.

Typical HTTP C<Accept-Language> headers are small, so the performance should be very good.

L<Apache2::API::Headers::AcceptCommon/preferences> and sorted results are cached per object.

=head1 CREDITS

Based on L<HTTP::AcceptLanguage> by Kazuhiro Osawa

=head1 AUTHOR

Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>

=head1 SEE ALSO

L<Apache2::API::Headers::Accept>, L<Apache2::API::Headers::AcceptCommon>, L<Locale::Unicode>, RFC 5646 (BCP 47), RFC 7231, RFC 9110.

L<Apache2::API::DateTime>, L<Apache2::API::Query>, L<Apache2::API::Request>, L<Apache2::API::Request::Params>, L<Apache2::API::Request::Upload>, L<Apache2::API::Response>, L<Apache2::API::Status>

L<Apache2::Request>, L<Apache2::RequestRec>, L<Apache2::RequestUtil>

=head1 COPYRIGHT & LICENSE

Copyright (c) 2023 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated
files under the same terms as Perl itself.

=cut